HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
TagView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA short label that adds metadata to content.StableSince 0.1.0MarkersUsageimport'@fusion.dev/helix/tag'import'@fusion.dev/helix-headless/tag'Preview
API ReferenceRoothelix-tagA short label that adds metadata to content.
PropTypeDescriptiondisabledbooleanDefaultfalseTakes the tag out of reach: its link and its remove button stop
answering, and in a Tag.Group the arrow keys pass over it and it cannot
be selected or removed.dismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Remove {label}"The dismiss control's label, read by screen readers.dismissTabStopbooleanDefaulttrueWhether the remove button is a tab stop of its own, outside a Tag.Group.emphasis"outlined"|"solid"|"subtle"How strongly the tag shows its tone: subtle, solid, or outlined.focusablebooleanWhether the tag holds its group's tab stop.hrefstringDefault""Makes the label a link to this address.selectedbooleanWhether the tag is selected, in a Tag.Group that selects.shape"pill"The tag's outline. pill rounds its ends fully, for a set of tags among
rounded controls. Absent is the theme's small radius.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The meaning the tag's color shows, such as success or danger.valuestringDefault""What the tag stands for in its group's value.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tag's label.dismiss-iconReplaces the glyph on the remove button.startThe category the label belongs to, shown before it in a heavier weight.
EventTypeDescriptionhelix-dismissHelixDismissEventThe remove button was pressed. The tag does not remove itself, so remove it in response. Cancelable.
MethodTypeDescriptiondismiss() => booleanFires helix-dismiss, and returns false if a listener cancels it.focusItem() => voidMoves focus to the tag: its cell in a group, and otherwise its link or
its remove button, whichever it has.
PartDescriptioncellThe grid cell in a Tag.Group, which takes focus and draws the ring round the whole tag.dismissThe remove button, when dismissible.dismiss-markThe icon on the remove button.labelThe label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.linkThe link around the label, under href.startThe category before the label.
CSS PropertyDescription--tag-background-colorThe fill behind the tag.--tag-border-colorThe color of the tag's edge.--tag-disabled-opacityHow strongly a disabled tag is drawn.--tag-font-weightThe weight of the label.--tag-foreground-colorThe label color.--tag-gapThe space between the category, the label and the remove button.--tag-radiusThe corner radius of the tag.
Custom stateDescriptionfocus-visibleThe tag's cell has keyboard focus that the browser shows, in a Tag.Group.selectedThe tag is selected in a Tag.Group that selects.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-tag-groupA set of tags that the arrow keys move through, and that can be removed and selected from the keyboard.
PropTypeDescriptiondisallowEmptySelectionbooleanDefaultfalseKeeps at least one tag selected once one is, as React Aria's
disallowEmptySelection: a press or a key that would leave none selected
is refused. Removing the last selected tag still takes it out of value.emptyLabelstringDefault"No tags"The words the group shows and says once its last tag is removed, where
nothing is in the empty slot.labelstringDefault""The name of the set, such as "Filters", which a screen reader announces
before its tags.selectionBehavior"replace"|"toggle"Default"toggle"What a press, Space, or a move does to the tags already selected.
toggle, the default, keeps them: a press adds or takes out the tag, and
the arrow keys move focus alone. replace selects the tag alone, as a
file list does, and the arrow keys carry the selection with focus.
Control or Command with a press or Space adds or takes out one tag in
multiple, and with an arrow moves focus without selecting.selectionModeTagSelectionModeHow many tags a reader can select: single, multiple, or none.valuestring|readonlystring[]Default""The selected tags' values, separated by commas with no space, as Toggle
Group and Table write theirs, since a value may hold a space. A value
written with a space after each comma is read the same way.
ReadTypeDescriptiontagsHelixHeadlessTag[]The tags the group holds, in order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tags, in the order they are read.emptyShown in place of the tags while there are none, such as "No filters". Its fallback is empty-label.
EventTypeDescriptionchangeEventFired once a press has changed which tags are selected.helix-before-changeHelixBeforeChangeEventFired before a press changes which tags are selected, with the value it would leave. Cancelable.helix-dismissHelixDismissEventA tag's remove button was pressed, or Delete or Backspace on the focused tag. Bubbles from that tag, which is its target; remove the tag in response. Cancelable.
PartDescriptionemptyHolds the empty slot while the group has no tags, rendered only then. Takes focus when the last tag is removed.
CSS PropertyDescription--tag-group-gapThe space between tags, across and between rows.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-tagA short label that adds metadata to content.
PropTypeDescriptiondisabledbooleanDefaultfalseTakes the tag out of reach: its link and its remove button stop
answering, and in a Tag.Group the arrow keys pass over it and it cannot
be selected or removed.dismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Remove {label}"The remove button's name, read by screen readers, with {label} for the
tag's own words.dismissTabStopbooleanDefaulttrueWhether the remove button is a tab stop of its own, outside a Tag.Group.focusablebooleanWhether the tag holds its group's tab stop.hrefstringDefault""Makes the label a link to this address.selectedbooleanWhether the tag is selected, in a Tag.Group that selects.valuestringDefault""What the tag stands for in its group's value.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tag's label.dismiss-iconReplaces the glyph on the remove button.startThe category the label belongs to, shown before it in a heavier weight.
EventTypeDescriptionhelix-dismissHelixDismissEventThe remove button was pressed. The tag does not remove itself, so remove it in response. Cancelable.
MethodTypeDescriptiondismiss() => booleanFires helix-dismiss, and returns false if a listener cancels it.focusItem() => voidMoves focus to the tag: its cell in a group, and otherwise its link or
its remove button, whichever it has.
PartDescriptioncellThe grid cell around everything the tag shows, rendered only in a Tag.Group, where it takes focus.dismissThe button that removes the tag.dismiss-markThe icon on the remove button.labelThe label, which the styled tag trims to its capitals and baseline so the letters sit at the middle in any font.linkThe link around the label, under href.startThe category before the label.
Custom stateDescriptionfocus-visibleThe tag's cell has keyboard focus that the browser shows, in a Tag.Group.selectedThe tag is selected in a Tag.Group that selects.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-headless-tag-groupA set of tags that the arrow keys move through, and that can be removed and selected from the keyboard.
PropTypeDescriptiondisallowEmptySelectionbooleanDefaultfalseKeeps at least one tag selected once one is, as React Aria's
disallowEmptySelection: a press or a key that would leave none selected
is refused. Removing the last selected tag still takes it out of value.emptyLabelstringDefault"No tags"The words the group shows and says once its last tag is removed, where
nothing is in the empty slot.labelstringDefault""The name of the set, such as "Filters", which a screen reader announces
before its tags.selectionBehavior"replace"|"toggle"Default"toggle"What a press, Space, or a move does to the tags already selected.
toggle, the default, keeps them: a press adds or takes out the tag, and
the arrow keys move focus alone. replace selects the tag alone, as a
file list does, and the arrow keys carry the selection with focus.
Control or Command with a press or Space adds or takes out one tag in
multiple, and with an arrow moves focus without selecting.selectionModeTagSelectionModeHow many tags a reader can select: single, multiple, or none.valuestring|readonlystring[]Default""The selected tags' values, separated by commas with no space, as Toggle
Group and Table write theirs, since a value may hold a space. A value
written with a space after each comma is read the same way.
ReadTypeDescriptiontagsHelixHeadlessTag[]The tags the group holds, in order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The tags, in the order they are read.emptyShown in place of the tags while there are none, such as "No filters". Its fallback is empty-label.
EventTypeDescriptionchangeEventFired once a press has changed which tags are selected.helix-before-changeHelixBeforeChangeEventFired before a press changes which tags are selected, with the value it would leave. Cancelable.helix-dismissHelixDismissEventA tag's remove button was pressed, or Delete or Backspace on the focused tag. Bubbles from that tag, which is its target; remove the tag in response. Cancelable.
PartDescriptionemptyHolds the empty slot while the group has no tags, rendered only then. Takes focus when the last tag is removed.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAppearancesTags in five tones with subtle, solid, and outlined emphasis.CategoryTags with a category in the start slot, shown before the label.DensityTags follow data-density, written on a region or on the tag itself, and stay the height of the buttons beside them.DismissibleTags you can remove, such as the filters in a filter bar.EventsPressing a tag's remove button sends helix-dismiss. The tag stays until your code removes it.GroupA tag group: the arrow keys move between tags, Delete removes one, and Space selects.PreviewA tag with the success tone.PreviewA tag with the success tone.