Usage
A tag is a compact label for a keyword or attribute. Group related tags with a Tag Group, which provides consistent spacing and an accessible grouping.
Import the parts you need — each import registers its custom element:
import "@nordhealth/components/lib/Tag"
import "@nordhealth/components/lib/TagGroup"
Then group a set of tags:
Composition
A Tag Group lays out a set of tags with consistent spacing.
TagGroup
├── Tag
└── Tag
<nord-tag-group aria-label="Patient flags">
<nord-tag>May bite</nord-tag>
<nord-tag>Has seizures</nord-tag>
</nord-tag-group>
Tag
Tag is a single label. The default tag is presentational; variant="selectable" makes it a toggle (use checked, name and value), and variant="removable" adds a control to dismiss it.
Tag Group
Tag Group lays out tags together. Use variant="spaced" for looser spacing, direction to stack them, and wrap to let them flow onto multiple lines. Give it an accessible name with aria-label or aria-labelledby.
Examples
Selectable
Use variant="selectable" to let people toggle tags on and off, like filters.
Removable
Use variant="removable" for tags people can dismiss, such as applied filters.
Selectable states
A single set of variant="selectable" tags showing the unchecked and checked states.
Selectable inside a form
Selectable tags participate in forms via name and value, submitting like checkboxes.
Disabled
Add disabled to make selectable and removable tags non-interactive.
Expanded
Use expand to make tags fill the available width.
Small size
Set size="s" for a more compact tag.
RTL
Tags follow the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- Give the Tag Group an accessible name (
aria-labeloraria-labelledby) so the set of tags is announced as a group. - Selectable and removable tags expose their state and controls to assistive technology; keep their labels concise and meaningful.
- Don't rely on colour alone to convey a tag's meaning — the label text should carry it.
API reference
Tag
Tags represent a set of keywords that help label, categorize, and organize objects. Commonly used to signify the attributes of an object.
<nord-accordion></nord-accordion>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
variant | variant | The behavioral variant of the tag. | 'default' | 'removable' | 'selectable' | 'default' |
checked | checked | Controls whether the tag is checked or not (only relevant when variant is set to selectable). | boolean | false |
size | size | The size of the tag. This affects the font-size. | 's' | 'm' | 'm' |
expand | expand | Controls whether the tag expands to fill the width of its container. | boolean | false |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
name | name | The name of the form component. | string | undefined | — |
value | value | The value of the form component. | string | '' |
form | form | Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. | HTMLFormElement | null | — |
Slots
| Slot name | Description |
|---|---|
Default slot | The tag content. |
Methods
| Method name | Parameters | Description |
|---|---|---|
focus(options?: FocusOptions) => void | options: An object which controls aspects of the focusing process. | Programmatically move focus to the component. |
blur() => void | N/A | Programmatically remove focus from the component. |
click() => void | N/A | Programmatically simulates a click on the component. |
| Event | Detail Type | Description |
|---|---|---|
change | NordEvent | Fired whenever the tag has been checked or unchecked via user interaction. |
remove | NordEvent | Fired when the remove button is activated. This event should be used to remove the tag from the DOM. |
Parts
This component is made up of the following parts.
Tag Group
Tag groups are designed to bring together selectable tags that are of a similar nature. For example categories you can filter by.
<nord-accordion-header></nord-accordion-header>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
variant | variant | The style variant of the tag group. | 'default' | 'spaced' | 'default' |
direction | direction | The direction of the tag group. | 'vertical' | 'horizontal' | 'horizontal' |
wrap | wrap | Defines whether the tags are forced in a single line
or can be flowed into multiple lines (only applied when variant is set to spaced). | boolean | false |
role | role | The appropriate role for the containing element. | string | 'group' |
Slots
| Slot name | Description |
|---|---|
Default slot | The tag group content |
| Event | Detail Type | Description |
|---|---|---|
change | NordEvent | Fired whenever a tag has been checked or unchecked via user interaction. |
remove | NordEvent | Fired when the remove button is activated on a tag. This event should be used to remove the tag from the DOM. |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-tag-group-border-radius | Controls the rounded corners of the tag group, using border radius tokens. Only relevant for the default variant. | var(--n-border-radius-s) |
--n-tag-group-box-shadow | Controls the surrounding shadow, using box shadow tokens. Only relevant for the default variant. | var(--n-box-shadow) |
Dependencies
This component is internally dependent on the following components:
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use for labeling, categorizing, or organizing objects.
- Ensure there is enough space around tags when they are interactive.
- Always position tags so that it’s easy to understand what object they’re related to.
- Keep in mind that tags can increase the amount of cognitive noise, particularly when combined with the status component, so use them in moderation.
Don’t
- Don’t use for showing the status of an object, use the badge component instead.
- Don’t use when you want to highlight something that has been added recently, use the badge component instead.
- Don’t use alternatives to existing tag variants.
Content guidelines
Tags should use short and clear labels for easy scanning. They should be concise and informative:
When writing tag labels, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Avoid unnecessary words and articles in tag labels, such as “the”, “an” or “a”:
Variants
This section describes the different component variants, their purpose, and when to use each variant.
| Name | Purpose |
|---|---|
default | The default variant for a non-interactive tag. |
removable | Used for tags that can be removed by the user. |
selectable | Used for tags that can be selected or deselected. |