Truncate

Accessibility and usability expectations

This component is intended to show a truncated version of its content, with the option for the user to expand it to see the content in its entirety.

For in-depth guidance on when and how to truncate accessibly, see Truncation patterns.

Built-in accessibility features

The component uses CSS to truncate text to a fixed size, with a title attribute containing the full content of the component. This triggers a native browser tooltip when the component is hovered with a mouse.

Because truncation is done purely via CSS, screen reader users can still read the entire content of the component.

Truncating static and interactive elements

The most accessible static element is one that is not truncated. It can be very tempting to place a tooltip on hover over a static truncation and call it complete; however, this is not available to keyboard-only and speech recognition users. Depending on the type of tooltip, it can also override the accessible name provided by the visible text.

For interactive elements, do not truncate text if it contains focusable elements such as links, buttons, and mentions/tags. This includes the focusable element itself as well as truncation that hides focusable elements. Similar to nested interactive controls, truncated focusable elements may not be available to all users, blocking them from potentially completing tasks.

Advice for handling truncation

Before truncating content, ask yourself:

• Can I wrap the text instead of truncating? Wrapping allows all text to be seen and creates a more consistent experience across screen widths.
• Can I give the element in question more real estate to expose all text? Truncating a small portion of text (a few characters, a word) adds friction to a UX that ultimately can be avoided.
• Can I use the progressive disclosure component to expand and collapse text instead? Primer's progressive disclosure utilizes explicit truncation, which requires an action to expand what is displayed. Because this information is available through a button, it gives access to assistive technology users.

Implementation requirements

Due to the current shortcomings of this component, consider alternative ways to provide a shortened version of content. The specific approach depends on the context of what you are building. For instance, you could truncate the content in your actual markup (rather than relying on CSS), or use the progressive disclosure pattern to expand and collapse content explicitly.

How to test the component

Integration tests

• Whenever the truncated content is presented to the user, there is a way for users to see the content in full. This method must work for all users, including keyboard users.