Tag
Tags represent a set of keywords that help label, categorize, and organize objects. Commonly used to signify the attributes of an object.
<sl-tag-list aria-label="Subjects">
<sl-tag>Mathematics</sl-tag>
<sl-tag>History</sl-tag>
</sl-tag-list>
<sl-tag-list aria-label="Selected subjects">
<sl-tag removable>Mathematics</sl-tag>
<sl-tag removable>History</sl-tag>
</sl-tag-list>When to use
Categorization, Labeling, and Filtering
Use tags to categorize and label course content, enhancing organization, discoverability, and enabling efficient filtering of content on a page, within components, or through search functionalities. For instance, courses or lessons can be tagged with subjects such as "Mathematics," "Science," "History," or "Literature." This approach makes it easier for users to quickly find and access relevant materials.
User-Generated Tags
Enable users to create and manage their own custom labels, allowing for a personalized organization system. In a student dashboard, for example, users might tag their notes or assignments with custom labels like "Exam Prep," "Homework," "Group Project," or "To Review," facilitating better organization.
Tag lists
Keep tag lists consistent: use either static tags or removable tags in a single list, but do not mix both types in the same list. A tag should only be disabled when it is also removable.
When not to use
Status Indicators
For tracking the status of tasks or items, such as "In Progress," "Completed," or "Pending," use a badge instead. Badges are specifically designed to convey status and can provide visual cues through colors, making them more effective for this purpose.
Anatomy tag
| Item | Name | Description | Optional |
|---|---|---|---|
| 1 | Container | The container contains the label and optional close button | no |
| 2 | Label | The label is a brief text that describes the tag | no |
| 3 | Close button | The only interactive part of a removable tag | yes |
Anatomy tag list
| Item | Name | Description | Optional |
|---|---|---|---|
| 1 | Counter | Displays the count of selected tags when not all tags are visible, with a maximum display of 99. If more than 99 tags are selected, it will be shown as "99+." | yes |
| 2 | List of tags | Consists of a collection of tags | no |
Figma Options
With these options, you can tweak the appearance of the tag in Figma. They are available in the Design Panel so you can compose the tag to exactly fit the user experience need for the use case you are working on.
Tag
| Item | Options | Description |
|---|---|---|
| Emphasis | subtle bold | Indicates the which emphasis the tag should have |
| State tag | idle hover active disabled | Indicates the state of the tag |
| State close | idle hover active disabled | Indicates the state of the close button |
| Size | md lg | Size 'md' is the default size of the tag component |
| Removable | boolean | Displays a close button |
| Label | value | The text of the label |
| Focus ring | boolean | To show the focus ring of the tag |
Tag list
| Item | Options | Description |
|---|---|---|
| Emphasis | subtle bold | Indicates the which emphasis the tag should have |
| Size | md lg | Indicates the size of the tag list |
| Items | 1 2 3 4 5 6 | Indicates how many tags are shown in the tag list |
| Stacked | boolean | Indicates if the tags are stacked, this will show a counter in front of the tag list |
<sl-tag-list stacked>
<sl-tag removable>Mathematics</sl-tag>
...
<sl-tag removable>English</sl-tag>
</sl-tag-list>Tag list API
Tag list component provides properties to define the experience in different use cases, and it is a kind of wrapper for multiple tags.
Properties
| Name | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | undefined | Disables removable tags in the tag list. | |
size | size | 'md' | 'lg' | undefined | 'md' | The size of the tag-list (determines size of tags inside the tag-list). |
stacked | stacked | boolean | undefined | false | This will hide tags that do not fit inside the available space when set. It will also display a counter that indicates the number of hidden tags. |
variant | variant | 'neutral' | 'info' | undefined | 'neutral' | The variant of the tag-list and tags inside. |
Slots
| Name | Description |
|---|---|
default | The place for tags. |
Tag API
Tag has a range of properties to define the experience in different use cases.
Properties
| Name | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | undefined | false | Whether the tag component is disabled, when set no interaction is possible. |
removable | removable | boolean | undefined | false | Whether the tag component is removable. |
size | size | 'md' | 'lg' | undefined | 'md' | The size of the tag. |
variant | variant | 'neutral' | 'info' | undefined | 'neutral' | The variant of the tag. |
Methods
| Name | Parameters | Return | Description |
|---|---|---|---|
focus | options?: FocusOptions | void |
Events
| Name | Event type | Description |
|---|---|---|
sl-remove | SlRemoveEvent | Emits when the tag is removed. |
Slots
| Name | Description |
|---|---|
default | The tag label. |
CSS Parts
| Name | Description |
|---|---|
label | The wrapper around the tag label. |
button | The remove button. |
Accessibility considerations
Do not mix static and removable tags in the same tag list. Use a static tag list when no tags can be removed, and a removable tag list when users can remove tags.
Keyboard interactions
The tag list component uses a roving tabindex for removable tags. You can focus the first remove button in the list by pressing the Tab key. After that, you can navigate through the remove buttons using the left and right arrow keys. The focus indicator loops, so when you are at the last option and press right it will focus on the first remove button. In the stacked version of tag-list, when there are hidden tags, you can navigate only through visible removable tags with arrow keys. The first tag indicates how many hidden tags there are. Using a screen reader, it will announce how many hidden tags there are.
When a remove button is focused, the tag can be removed by activating the button or by pressing the Delete or Backspace key. The remove button has an accessible name that includes the tag label, for example "Remove tag 'History'".
WAI-ARIA
In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.
Attributes that we recommend you add in certain scenarios are mentioned below.
Tag
| Attribute | Value | Description |
|---|---|---|
role | 'listitem', 'button' | Identifies the tag element as a listitem when it's used inside the sl-tag-list - this role is added automatically. Please provide a role button when the tag is interactive, is used to perform an action or is removable and not used inside sl-tag-list. |
Tag list
| Attribute | Value | Description |
|---|---|---|
aria-label | string | String that labels the tag list. Use this to label what the tag list indicates, such as the selected options in a combobox. |
aria-labelledby | string | Can be used to connect with a single header/element that describes the tag list. |