Skip to content

docs(sp-truncated): updated sp-truncated pattern #5839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs(sp-truncated): updated sp-truncated pattern #5839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
78be3f6
docs: updated sp-truncated pattern
Oct 28, 2025
69e086b
chore: updated guidelines text
Oct 30, 2025
1fa7876
Merge branch 'main' into rajdeep/truncated-docs
Rajdeepc Oct 30, 2025
b1e52d9
Merge branch 'main' into rajdeep/truncated-docs
Nov 6, 2025
ddb5353
Merge branch 'main' into rajdeep/truncated-docs
Nov 6, 2025
a1357d1
Merge branch 'main' into rajdeep/truncated-docs
Rajdeepc Nov 7, 2025
096681d
chore: updated text to show custom message
Nov 10, 2025
caefec6
Merge branch 'main' into rajdeep/truncated-docs
Rajdeepc Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions 1st-gen/tools/bundle/elements.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,4 +98,5 @@ import '@spectrum-web-components/tooltip/sp-tooltip.js';
import '@spectrum-web-components/top-nav/sp-top-nav.js';
import '@spectrum-web-components/top-nav/sp-top-nav-item.js';
import '@spectrum-web-components/tray/sp-tray.js';
import '@spectrum-web-components/truncated/sp-truncated.js';
import '@spectrum-web-components/underlay/sp-underlay.js';
228 changes: 210 additions & 18 deletions 1st-gen/tools/truncated/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,241 @@
## Description
## Overview

`<sp-truncated>` renders a line of text, truncating it if it overflows its container. When overflowing, a tooltip is automatically created
that renders the entire non-truncated content.
`<sp-truncated>` renders a line of text, truncating it if it overflows its container. When overflowing, a tooltip is automatically created that renders the entire non-truncated content. Additionally, clicking on overflowing text copies the full content to the clipboard and displays a success message.

It is used like a `<span>` to contain potentially-long strings that are important for users to see, even when in small containers, like full
names and email addresses.
This component is designed like a `<span>` to contain potentially-long strings that are important for users to see, even when in small containers, such as full names, email addresses, file paths, and other text data that may exceed the available space.

### Usage

[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/truncated?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/truncated)
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/truncated?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/truncated)

```
```bash
yarn add @spectrum-web-components/truncated
```

Import the side effectful registration of `<sp-truncated>` via:
Import the side effectful registration of `<sp-truncated>` as follows:

```
```typescript
import '@spectrum-web-components/truncated/sp-truncated.js';
```

When looking to leverage the `Truncated` base class as a type and/or for extension purposes, do so via:

```
```typescript
import { Truncated } from '@spectrum-web-components/truncated';
```

## Example
### Anatomy

The basic structure of the truncated component:

```html
<sp-truncated>
This will truncate into a tooltip if there isn't enough space for it.
</sp-truncated>
```

### With specific overflow content
### Examples

#### Basic usage

By default, `<sp-truncated>` will automatically detect when text overflows its container and display a tooltip with the full content on hover. When the truncated text is clicked, it copies the full text to the clipboard.

```html demo
<div
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px; overflow: hidden; resize: both;"
>
<sp-truncated>
This is a very long sentence that should be truncated when there isn't
enough space to display it fully.
</sp-truncated>
</div>
```

#### With mixed content

`<sp-truncated>` supports mixed content including text formatting and inline elements:

```html demo
<div
style="width: 250px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated>
This is a
<strong>very long</strong>
sentence with
<em>formatted text</em>
that should be truncated.
</sp-truncated>
</div>
```

#### Long words without spaces

The component handles long words or strings without spaces appropriately:

```html demo
<div
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated>
ThisIsAVeryLongWordWithoutAnySpacesThatShouldBeTruncated
</sp-truncated>
Comment on lines +81 to +83
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example isn't working on the docs page as the tooltip does not show the entire content.

</div>
```

#### Custom overflow content

By default, tooltip text will be extracted from the overflowing content. To provide your own custom overflow content for the tooltip, slot it into the `overflow` slot:

```html demo
<div
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated>
This is the inline content that gets truncated
<span slot="overflow">
This custom overflow content will appear in the tooltip with any
additional information or formatting you need.
</span>
</sp-truncated>
Comment on lines +95 to +101
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed in the examples that only This is the inline content that gets is displayed and in the tooltip This custom overflow content will appear in the tooltip with any additional information or formatting you need gets displayed, which means, neither the truncated text nor the tooltip show the word truncated (ironic).

Should everything before the overflow be displayed, i.e This is the inline content that gets truncated? Or is this working as designed?

If the latter is true, we should warn consumers that setting the overflow might cause some words to be neither visible in the truncated line nor the tooltip.

Copy link
Contributor

@caseyisonit caseyisonit Nov 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why would we even include content in an overflowed slot that isnt the actual text? im needing a use case to understand how and when this should be used in product. its feeling like a dark UX pattern.

</div>
```

#### Tooltip placement

You can control the placement of the tooltip using the `placement` attribute. The default placement is `top-start`.

```html demo
<div style="display: flex; gap: 16px; flex-wrap: wrap;">
<div
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated placement="top">
Top placement for this truncated text
</sp-truncated>
</div>
<div
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated placement="bottom">
Bottom placement for this truncated text
</sp-truncated>
</div>
<div
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated placement="left">
Left placement for this truncated text
</sp-truncated>
</div>
<div
style="width: 150px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated placement="right">
Right placement for this truncated text
</sp-truncated>
</div>
</div>
```

#### Custom success message

When text is copied to the clipboard, a custom success message can be displayed:
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried copying the text, and while I got the success message, when I pasted I noticed the copy wasn't the full text.

I didn't realize that the act of clicking the div would copy the whole thing.

Copy link
Contributor

@caseyisonit caseyisonit Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

again this feels like a dark pattern, does this mean that anything wrapped in a truncated is keyboard navigable? how would this functionality work for now mouse users? what visual queue are we providing that its copyable?


```html demo
<div
style="width: 200px; border: 1px solid var(--spectrum-gray-300); padding: 8px;"
>
<sp-truncated success-message="Email copied successfully!">
[email protected]
</sp-truncated>
</div>
```

### Usage in patterns

By default, tooltip text will be extracted from overflowing content. To provide your own overflow content, slot it into "overflow":
#### With field labels

`<sp-truncated>` is commonly used with form fields to display long values that might overflow:

```html demo
<sp-field-label for="email-field">Email address</sp-field-label>
<div
style="width: 250px; border: 1px solid var(--spectrum-gray-300); padding: 8px; border-radius: 4px;"
>
<sp-truncated>[email protected]</sp-truncated>
</div>
Comment on lines +164 to +168
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be a field instead of a div? Field labels should only be used with interactive elements, such as form fields.

```

#### In popovers

For use within overlays, ensure the popover has appropriate width constraints:

```html
<sp-truncated placement="right">
This is the inline content
<span slot="overflow">
And this overflow content will go into the tooltip, on the right
</span>
</sp-truncated>
<sp-button id="user-trigger">User Info</sp-button>
<sp-overlay trigger="user-trigger@click" placement="bottom">
<sp-popover style="width: 250px;">
<div style="padding: 16px;">
<sp-field-label>Username</sp-field-label>
<div style="width: 200px;">
<sp-truncated>
very.long.username.that.exceeds.the.available.width
</sp-truncated>
Comment on lines +182 to +184
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tooltip here is also not displaying the full content.

</div>
</div>
</sp-popover>
</sp-overlay>
```

### Accessibility

#### Keyboard navigation

The `<sp-truncated>` component does not receive keyboard focus by itself, as it functions as inline content. However, the tooltip that appears on hover follows standard Spectrum tooltip accessibility patterns:

- The tooltip appears on hover and focus
- The tooltip is dismissed when the user moves away or presses the Escape key

#### Click to copy

When truncated text is clicked, the full text content is copied to the clipboard. This interaction provides a quick way for users to access the complete content.

**Important accessibility note:** The click handler on the truncated text does not include keyboard event handlers (`/* eslint-disable lit-a11y/click-events-have-key-events */`). This is a known limitation. Users who rely on keyboard navigation will need to use the tooltip hover interaction to view the full content, but cannot copy it via keyboard alone.

#### Screen readers

Screen readers will announce the visible truncated text. When the tooltip appears on hover, screen readers will announce the full content if it differs from the visible text.

For custom overflow content, ensure that the slotted content is semantically meaningful and properly structured for screen readers.
Comment on lines +204 to +210
Copy link
Contributor

@nikkimk nikkimk Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Since the sp-truncated does not receive keyboard focus, a keyboard user will never be able to tooltip hover.
  • Screenreader users--who are very often but not always keyboard users---will hear the full content without the tooltip.
  • Not all keyboard users are screenreader users, so this is an accessibility bug.

Copy link
Contributor

@caseyisonit caseyisonit Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a very interesting thread in the a11y channel on slack specifically about truncation and how its actually an inaccessible pattern as a whole. we might want to bring this up in one of our team meetings


### Content guidelines

#### Do

- Use `<sp-truncated>` for non-critical text that users may need to see in full but can afford to be shortened in compact views
- Provide meaningful text that makes sense even when truncated
- Use for email addresses, file paths, long names, and similar data
- Test with actual content to ensure the truncation point makes sense

#### Don't

- Don't use for critical actions or navigation labels that must always be visible
- Don't use for very short text that is unlikely to overflow
- Don't truncate text where the beginning or end context is essential for comprehension
- Don't rely solely on truncated text for important information without providing alternative access

### Additional resources

For more information on accessibility best practices for truncated text, refer to:

- [Spectrum Design System - Text Overflow Guidelines](https://spectrum.adobe.com/page/text-field/#Text-overflow)
- [WCAG 2.1 Success Criterion 1.4.8 - Visual Presentation](https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html)

### Design reference

For design specifications and usage guidelines, refer to the Spectrum Design System documentation:

- [Spectrum Text Field Component - Text Overflow](https://spectrum.adobe.com/page/text-field/#Text-overflow)

**Note:** While `<sp-truncated>` is not a standalone component in the official Spectrum Design System, it implements common text truncation patterns used throughout Spectrum components.
Loading