Tag group

Overview

link

Web

tanrei-tag-group

schedule

SwiftUI

TanreiTagGroup

radio_button_unchecked

Jetpack Compose

TanreiTagGroup

radio_button_unchecked

Flutter

TanreiTagGroup

radio_button_unchecked

React Native

TagGroup

radio_button_unchecked

Generated from docs/status/status.json, specs/tag-group.spec.json

A set of tags, and a row of filters

A tag and a chip are each one thing. A tag group is what holds several of them: the tags of an article, the filters above a list, a few suggestions under a field. It places them in lines that wrap, keeps the right distance between them, and tells assistive technology that they are one list.

The group draws nothing of its own. It has no container, no edge, no padding and no visible label. Each member is drawn, focused and pressed exactly as it is anywhere else.

On the web it is <tanrei-tag-group>. The other platforms have not implemented it yet.

Usage

link

<!-- A set of static tags says so: its lines stand as close as its tags. -->
<tanrei-tag-group spacing="tags" label="Tags">
  <tanrei-tag label="Design tokens"></tanrei-tag>
  <tanrei-tag label="Accessibility"></tanrei-tag>
</tanrei-tag-group>

<!-- A set of chips takes the default spacing: its lines stand far enough apart for each chip's touch target. -->
<tanrei-tag-group id="recipients" label="Recipients">
  <tanrei-chip kind="input" label="Ada Lovelace" remove-label="Remove Ada Lovelace"></tanrei-chip>
  <tanrei-chip kind="input" label="Grace Hopper" remove-label="Remove Grace Hopper"></tanrei-chip>
</tanrei-tag-group>

<script type="module">
  import '@tanrei/web/components/tag-group';
  import '@tanrei/web/components/tag';
  import '@tanrei/web/components/chip';

  const recipients = document.querySelector('#recipients');
  // A chip never removes itself. You take it out; the group moves focus to the next chip.
  recipients.addEventListener('remove', (event) => {
    event.target.remove();
    // When the last one has gone, the group has nowhere to put focus. Put it on the control the set belongs to.
    if (!recipients.children.length) document.querySelector('#add-recipient').focus();
  });
</script>

import { Chip, TagGroup } from '@tanrei/react';

<TagGroup label="Recipients">
  {recipients.map((person) => (
    <Chip key={person.id} kind="input" label={person.name} removeLabel={`Remove ${person.name}`} onRemove={() => remove(person.id)} />
  ))}
</TagGroup>

Specs

link

Tags that wrap, status tags, links to each tag’s page, and entered items

Anatomy

Part	Description
1 group	The set: lines of members that start at the start edge and wrap. It draws nothing of its own — no container, no fill, no edge, no padding and no label — and is exposed as one list.
2 member	A tag or a chip of the set: placed and spaced by the group, exposed as an item of its list, and otherwise drawn and behaving as it does anywhere.

Properties

Property	Type	Default	Description
spacing	tags | chips	"chips"	What the set holds, which decides the distances between its members. tags: static tags, as close as words of one group. chips: chips, which take input, with lines far enough apart that each chip keeps its whole touch target.
label	string	""	The accessible name of the set ("Tags", "Filters", "Suggested fonts"). It is not drawn: a set that needs a visible name stands under the product's own heading or text, and still takes this. Optional where the set is plain from what surrounds it, recommended for a set of chips.
selection	none | single | multiple	"none"	Whether the group holds the selection of its filter chips. none: it holds none, and each filter chip holds its own selected, as alone. single: at most one filter chip is on at a time, named by value. multiple: any number are on, named by values. While it is single or multiple the set is one Tab stop and the arrow keys move between its chips.
value	string	null	The value of the filter chip that is on while selection is single; null puts none on. The group sets it when a person switches a chip and emits change; the product may also set it.
values	strings		The values of the filter chips that are on while selection is multiple: a list of strings (the platforms take a set). An empty list puts none on.

Events

Event	Description
change	While selection is single or multiple, a person switched a filter chip of the set: carries value (single) or values (multiple) after the change, which the group now holds. In place of the chip's own change, which stops at the group (TGR-19).

Items

The kinds of item the component repeats. A fixture lists its items in order; each platform names each kind in its own idiom.

tag

A Tag of the set: the tag component, placed and spaced by the group and exposed as an item of its list, otherwise drawn and read as it is anywhere.

Property	Type	Default	Description
label	string	""	Its text, as the Tag's label.
variant	tonal | outlined | filled	"tonal"	Its look, as the Tag's variant.
status	default | info | warning | error | success	"default"	What it reports, as the Tag's status.
size	small | medium	"medium"	Its height, as the Tag's size. Give every member of a group the same size.
icon	string	""	The glyph in the Tag's icon slot, by its name in the system's icon set. Empty for none. It is how a fixture fills that slot; in an application the slot is filled as the Tag's own spec says.

Spec	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Item	tanrei-tag	TanreiTag	TanreiTag	TanreiTag	Tag
label · Property	label	title	label	label	label
variant · Property	variant	variant	variant	variant	variant
status · Property	status	status	status	status	status
size · Property	size	size	size	size	size
icon · Property	slot="icon"	icon	icon	icon	icon
Notes	A tanrei-tag child, as anywhere.	A TanreiTag child, as anywhere.	A TanreiTag call in the group's content, as anywhere.	A TanreiTag in children, as anywhere.	A Tag child, as anywhere.

chip

A Chip of the set: the chip component, placed and spaced by the group and exposed as an item of its list, otherwise drawn and behaving as it does anywhere, with its own state, events and Tab stop.

Property	Type	Default	Description
kind	action | filter | input	"action"	What it does, as the Chip's kind.
label	string	""	Its text and accessible name, as the Chip's label.
size	small | medium	"medium"	Its height, as the Chip's size. Give every member of a group the same size.
selected	boolean	false	Whether a filter chip is on, as the Chip's selected. While selection is none the chip holds it; while selection is single or multiple the group sets it from value or values (TGR-17).
value	string	""	What the group's value and values name a filter chip by, as the Chip's value. Unique within the set; needed while selection is single or multiple.
disabled	boolean	false	As the Chip's disabled: one chip of a set may be disabled by itself.
href	string	""	The destination of an action chip, as the Chip's href: it makes the chip a link.
removeLabel	string	""	The accessible name of an input chip's remove action, as the Chip's removeLabel.
icon	string	""	The glyph in the Chip's icon slot, by its name in the system's icon set. Empty for none. It is how a fixture fills that slot; in an application the slot is filled as the Chip's own spec says.

Event	Description
click	The chip was activated, as the Chip's click.
change	A filter chip was switched, as the Chip's change. While selection is single or multiple it stops at the group, whose own change carries the selection (TGR-19).
remove	The person asked to remove an input chip, as the Chip's remove. The product removes it; the group then places the rest and moves focus (TGR-9).

Spec	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Item	tanrei-chip	TanreiChip	TanreiChip	TanreiChip	Chip
kind · Property	kind	isSelected / onRemove	onSelectedChange / onRemove	TanreiChip / TanreiChip.filter / TanreiChip.input	kind
label · Property	label	title	label	label	label
size · Property	size	size	size	size	size
selected · Property	selected	isSelected	selected	selected	selected
value · Property	value	value	value	value	value
disabled · Property	disabled	disabled	enabled	isEnabled	disabled
href · Property	href	destination	href	href	href
removeLabel · Property	removeLabel	removeLabel	removeContentDescription	removeSemanticLabel	removeAccessibilityLabel
icon · Property	slot="icon"	icon	icon	icon	icon
click · Event	click	action	onClick	onPressed	onPress
change · Event	change	isSelected	onSelectedChange	onSelected	onSelectedChange
remove · Event	remove	onRemove	onRemove	onDeleted	onRemove
Notes	A tanrei-chip child, as anywhere; remove-label is its attribute. The page removes the element on remove; the group sees it leave and moves focus (TGR-9).	A TanreiChip child, as anywhere.	A TanreiChip call in the group's content, as anywhere; enabled is disabled's inverse.	A TanreiChip in children, as anywhere. Give each a Key, so that the group can tell which one left.	A Chip child, as anywhere. Give each a key, so that the group can tell which one left.

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID	Requirement
TGR-1	THE tag group SHALL lay out its members in lines: from its start edge, in the order they were given, comp.tag-group.gap.tags apart along a line WHILE spacing is tags and comp.tag-group.gap.chips apart WHILE spacing is chips, each member at its own size and centred on the middle of its line. It SHALL be as wide as its layout gives it and as tall as its lines, SHALL draw no container, fill, edge or elevation of its own, SHALL add no padding around its members, and SHALL NOT draw its label.
TGR-2	WHEN a member does not fit in what is left of a line THE tag group SHALL put it, whole, at the start of a new line below, comp.tag-group.row-gap.tags below the line above WHILE spacing is tags and comp.tag-group.row-gap.chips WHILE spacing is chips, measured between the visible bounds of the tallest members of the two lines; it SHALL NOT cut, shrink or split a member to keep it on a line, SHALL NOT scroll its lines, and SHALL NOT hide a member or stand a count in its place: every member it is given is shown. WHERE one member alone is wider than the group THE tag group SHALL give it the group's width on a line of its own, and the member SHALL then cut its own label as its own spec says (TAG-5, CHP-17).
TGR-3	THE tag group SHALL keep its members in the order they were given: it SHALL NOT sort them, move a selected chip forward or group them by kind, and the order in which focus moves through its chips and in which assistive technology reads its members SHALL be that order — along each line from its start, and line after line from the top.
TGR-4	THE tag group SHALL take from spacing only the distances of TGR-1 and TGR-2: spacing SHALL NOT change what a member is, how it is drawn or what the group exposes. WHERE the platform can tell what its members are, WHILE spacing is tags and a member takes input (a chip) THE tag group SHALL still render and in debug builds report that a set of chips wants spacing chips, because the lines of tags stand closer than a chip's touch target is high.
TGR-5	WHILE the hit areas that two neighbouring chips extend beyond their visible bounds (CHP-5, CHP-21) overlap THE tag group SHALL give every press on a chip's visible bounds to that chip, and a press in the gap between two chips — along a line or between two lines — to the nearer one, so that neighbouring hit areas meet at the middle of the gap. comp.tag-group.row-gap.chips is what keeps each chip's target whole between two lines: at sys.target.touch minus a chip's height or more, no hit areas overlap, as under the default system's value for a medium chip; a small chip on wrapped lines, and a layer that narrows the gap, have targets that meet between the lines.
TGR-6	THE tag group SHALL NOT restyle its members: each SHALL render from its own tokens at its own size, answer hover, focus and press itself, hold its own state (a filter chip its selected, which the group sets WHILE selection is single or multiple, TGR-17), emit its own events (but the change of a filter chip the group holds, TGR-19) and keep its own role and name inside the item the group exposes it as (TGR-7). WHILE selection is none each chip SHALL be its own Tab stop — an input chip one, the chip itself, whose remove action is not a stop and which Backspace or Delete removes (CHP-18, CHP-19, CHP-23) — in the order of TGR-3, and the tag group SHALL NOT handle arrow keys, Home or End, SHALL keep no selection of its own, SHALL NOT make its filter chips exclusive, and SHALL emit no event; what a selection changes is TGR-17 to TGR-21. The tag group itself SHALL NOT take focus, whatever its selection. The tag group has no size of its own: members of different sizes on one line are centred on it (TGR-1).
TGR-7	WHILE the tag group holds at least one member THE tag group SHALL expose itself to assistive technology as a list, named by label WHILE label is not empty, and each member as one item of that list, in the order of TGR-3, holding the member as the member exposes itself: a tag as its text (TAG-11), a chip as its button or its link with its state, an input chip with its remove action beside it. WHEN label changes THE tag group SHALL expose the new name at once. WHILE label is empty THE tag group SHALL still expose the list, unnamed. A platform that has no list role SHALL expose a container named by label that holds the members in order, and state that in its README.
TGR-8	WHILE the tag group holds no member THE tag group SHALL draw nothing, take no space and expose nothing — no empty list and no name — and SHALL report nothing: a set that has no tags yet, or whose last filter was removed, is not a mistake. WHILE it holds one member THE tag group SHALL lay it out and expose it as a list of one.
TGR-9	WHEN a member leaves the tag group while focus is on it — on a chip or on its remove action — THE tag group SHALL move focus to the chip that follows it in the order of TGR-3, or to the chip before it WHERE none follows, on the chip itself and never on its remove action, so that a person who removes several entered items in a row goes on from where they were; it SHALL skip a member that takes no focus (a tag, a disabled chip). WHERE no member that takes focus is left THE tag group SHALL NOT move focus, having nowhere of its own to put it: the product moves it to the control that the set belongs to (CHP-22). THE tag group SHALL NOT remove a member itself and SHALL announce nothing.
TGR-10	WHEN a member is added, is removed or changes its size THE tag group SHALL place its members again by TGR-1 and TGR-2 and SHALL move every member whose place that changes from where it was drawn to its new place over comp.tag-group.motion.move-duration with comp.tag-group.motion.move-easing, along its line and from one line to another, without fading or scaling it; a change that comes while members move SHALL take each of them on from where it is drawn. A member that is added SHALL appear in its place at once and one that is removed SHALL leave at once. WHILE a line holds the same members in the same order as before the change, its members SHALL follow the change at once: a member that changes its size, at once or over a motion of its own, carries the members after it on its line, and a line whose height changes carries the lines below. THE tag group's own height SHALL follow its lines at once, and WHEN the width the layout gives the tag group changes THE tag group SHALL place its members again at once. WHERE motion is reduced THE tag group SHALL place its members again at once. A member that has focus while it moves SHALL keep it, its focus indicator moving with it, and THE tag group SHALL NOT move focus because a member was added.
TGR-11	WHILE the tag group holds content that is not a Tanrei tag or chip THE tag group SHALL still lay it out and expose it as a member, and in debug builds report it; a platform that cannot inspect its content SHALL state the rule in its README and docs page.
TGR-12	WHILE the text size is enlarged THE tag group SHALL keep its gaps and let its members grow as their own specs say (TAG-13, CHP-17), wrapping onto as many lines as they then need; at 200% no member SHALL be lost, lie over another or be cut by the group, and the group SHALL need scrolling in no direction of its own.
TGR-13	WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE tag group SHALL draw nothing of its own there either: its members draw themselves as their own specs say (TAG-14), and the distances of TGR-1 and TGR-2 stay what tells them apart.
TGR-14	WHERE the layout direction is right-to-left THE tag group SHALL start every line at the right edge and place its members from right to left, in the order they were given, wrapping to a new line below as TGR-2 says; the order of focus and of reading SHALL stay the order of TGR-3. Each member's own content SHALL follow the layout direction as the member's spec says (TAG-15, CHP-25).
TGR-15	THE tag group SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the tag group is shown THE tag group SHALL draw itself for the new direction at once, without a motion of its own, keeping its members, their state and their focus.
TGR-16	WHEN spacing names a value that the active design system does not have THE tag group SHALL render with the default value's tokens, and in debug builds report the unknown value.
TGR-17	WHILE selection is single or multiple THE tag group SHALL hold the selection of its filter chips by their value: it SHALL set each filter chip's selected to whether value equals the chip's value (single) or values holds it (multiple) WHEN selection, value or values changes, WHEN a filter chip arrives and WHEN a chip's value or kind changes, so that what each chip shows and exposes as its pressed state (CHP-11) is always the group's selection. A chip that is not a filter chip, a tag and other content take no part in it, and are laid out, reached and exposed as WHILE selection is none. WHEN value or values names no member THE tag group SHALL put nothing on for that name and report nothing, because a filter whose chip was taken away is not a mistake; WHEN a member leaves THE tag group SHALL leave value and values as they are and emit nothing. WHEN selection becomes none THE tag group SHALL leave each chip's selected as it then is and hold it no longer. WHEN selection names a value it does not have THE tag group SHALL behave as WHILE it is none, and in debug builds report the value.
TGR-18	WHILE selection is single or multiple, WHERE a filter chip's value is empty THE tag group SHALL leave that chip out of its selection — it keeps its own selected and its own change, as WHILE selection is none — and WHERE two filter chips share a value THE tag group SHALL put them on and off together, because they name one thing; in debug builds it SHALL report each, and it SHALL render either way.
TGR-19	WHEN the person switches a filter chip that has a value — by pointer, touch, Enter, Space or assistive technology — WHILE selection is single THE tag group SHALL set value to the chip's value WHERE the chip is now on, and switch every other filter chip off, or to null WHERE it is now off, because each chip is a toggle that says it is pressed and a pressed toggle that cannot be released would be untrue; WHILE selection is multiple THE tag group SHALL add the chip's value to values WHERE the chip is now on, or take it out WHERE it is now off. THE tag group SHALL then emit change exactly once, carrying value (single) or values (multiple), which it already holds, and SHALL stop the chip's own change at the group, so that a listener on the group or above it hears one change that carries the selection. THE tag group SHALL emit nothing WHEN the product sets selection, value or values.
TGR-20	WHILE selection is single or multiple and the group holds a chip that takes focus THE tag group SHALL be one stop in the focus order, in place of the stops TGR-6 gives each chip: the chip that last had focus WHILE it is still in the group and takes focus, otherwise the first filter chip that is on, otherwise the first chip that takes focus; every other chip, and with it its remove action, SHALL be out of the Tab order and stay focusable by the keys of this rule, by pointer and touch, and by assistive technology. WHILE a chip of the group has focus THE tag group SHALL move focus, without switching or removing anything: on Right Arrow to the chip drawn after it and on Left Arrow to the one drawn before it — in a right-to-left layout the same two keys the other way, so that an arrow always moves the way it points — on Home to the first chip and on End to the last, passing every member that takes no focus (a tag, a disabled chip); focus SHALL NOT wrap, and Up Arrow and Down Arrow SHALL do nothing: the members are one row in their order, however many lines draw it. Enter and Space SHALL stay the focused chip's own — Space switches a filter chip (CHP-11) — and so SHALL Backspace and Delete on an input chip (CHP-19).
TGR-21	WHILE selection is single or multiple, WHEN a member leaves while focus is on it THE tag group SHALL move focus as TGR-9 says, and the chip that then has focus SHALL be the set's stop; WHEN the chip that was the set's stop leaves, is disabled or no longer takes focus while focus is elsewhere THE tag group SHALL make a stop as TGR-20 says of a group whose last-focused chip is gone, so that the set keeps exactly one stop while it holds a chip that takes focus. WHEN selection becomes none THE tag group SHALL give each chip its own stop again.
TGR-22	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE tag group SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its list — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label is not empty it is the list's name, over a name given so; WHILE label is empty, a name given so is the list's name. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE tag group SHALL take it off that element.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Component	tanrei-tag-group	TanreiTagGroup	TanreiTagGroup	TanreiTagGroup	TagGroup
spacing · Property	spacing	spacing	spacing	spacing	spacing
label · Property	label	label	contentDescription	semanticLabel	accessibilityLabel
selection · Property	selection	selectionMode	selectionMode	selectionMode	selectionMode
value · Property	value	selection	selectedValue	selectedValue	value
values · Property	values	selection	selectedValues	selectedValues	values
change · Event	change	selection	onSelectionChange	onSelectionChanged	onSelectionChange
Notes	<tanrei-tag-group label="Filters" spacing="chips"> holds tanrei-tag and tanrei-chip children. The members stay in the product's light DOM, in the default slot: they keep their attributes, events, styles and place in the document, and the group moves none of them. The shadow root holds one element with role="list" and aria-label, a flex container that wraps (flex-wrap: wrap; align-items: center; column-gap; row-gap from the tokens of spacing), around the slot; the host has no role, and the group gives each slotted member role="listitem" where it has no role of its own and takes it back when the member leaves (slotchange), as the carousel exposes its items. A tanrei-chip host carries no role itself — its button or link is in its shadow root — so the item holds that control. While the slot is empty the host is display: none and the list is not rendered (TGR-8). Removal: a MutationObserver and slotchange find a member that left while :focus-within held on it, and the group calls focus() on the next chip (TGR-9). The debug report of TGR-4 looks for a tanrei-chip among the slotted elements. Before the element is defined its children are already shown, as the inline elements they are, in source order and separated by the white space between them: a set of tags is readable and a set of chips is operable once the chips themselves are defined; a page that wants the final layout from the first paint adds tanrei-tag-group:not(:defined) { display: flex; flex-wrap: wrap; gap: … } with the token's custom properties. The host is display: block. Selection (TGR-17 to TGR-21): selection and value are attributes and properties; values is a property (an array), and the values attribute is also read, as JSON or as space-separated words, because the fixture harness writes attributes. A chip's value is the tanrei-chip's own value. While selection is single or multiple the group writes each filter chip's selected, stops the chip's change at the host and dispatches its own change (detail.value or detail.values), and gives every chip but the set's stop tabindex="-1" (a host that delegates focus with a negative tabindex is out of the Tab order, with everything in its shadow root), taking back only the tabindex it gave; it handles the arrow keys, Home and End from a keydown listener on the host.	TanreiTagGroup(_ label: String = "", spacing: .chips) { TanreiChip(…) … }: a custom Layout that flows its subviews into lines by TGR-1 and TGR-2 and follows layoutDirection. The container is .accessibilityElement(children: .contain) with the label; SwiftUI has no list trait for an arbitrary layout, so VoiceOver reads the label and then each member (TGR-7's fallback). Focus after a removal uses @AccessibilityFocusState and @FocusState keyed by the members' identities, which the caller gives with .id(_:) as in a ForEach. Selection: TanreiTagGroup(selection: $value) with a Binding<String?> (single) or a Binding<Set<String>> (multiple), each chip given its value as TanreiChip(value:); the arrow keys come from focusable() and onMoveCommand.	TanreiTagGroup(spacing = TanreiTagGroupSpacing.Chips, contentDescription = "Filters") { … }, built on FlowRow with the tokens' horizontal and vertical arrangements. Semantics: a traversal group with contentDescription and collectionInfo (one row, as many columns as members), each member given collectionItemInfo; TalkBack then reads the count. Focus after a removal: the group keeps a FocusRequester per member key and requests the next one when a focused member leaves the composition.	TanreiTagGroup(spacing: TanreiTagGroupSpacing.chips, semanticLabel: 'Filters', children: […]), built on Wrap with spacing, runSpacing and crossAxisAlignment: WrapCrossAlignment.center; Wrap follows Directionality. Semantics(container: true, label:) around it; Flutter has no list role for a Wrap, so the members are read in order after the label. Focus after a removal: the group compares its children's keys between builds and requests focus on the next chip's FocusNode.	<TagGroup spacing="chips" accessibilityLabel="Filters">{…}</TagGroup>: a View with flexDirection: 'row', flexWrap: 'wrap', alignItems: 'center', columnGap and rowGap from the tokens, accessibilityRole="list" (announced on Android; a labelled container on iOS). It reads its children's keys to find the chip that follows a removed one and focuses it through its ref. Follows the app's direction where an ancestor's is not known.

Tokens

Token	Aliases	Resolved (light)
--tanrei-comp-tag-group-gap-chips	sys.space.space100	8px
--tanrei-comp-tag-group-gap-tags	sys.space.space100	8px
--tanrei-comp-tag-group-motion-move-duration	sys.motion.role.selection.travel	250ms
--tanrei-comp-tag-group-motion-move-easing	sys.motion.easing.spatial	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-tag-group-row-gap-chips	sys.space.space200	16px
--tanrei-comp-tag-group-row-gap-tags	sys.space.space100	8px

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

spacing: tags (12)

tags

spacing: tags label: Tags items: 3

tags-outlined

spacing: tags label: Tags items: 4

tags-small

spacing: tags label: Sizes items: 3

tags-status

spacing: tags label: Platforms items: 5

tags-current

spacing: tags label: Choices items: 2

tags-icons

spacing: tags label: Tags items: 3

tags-single

spacing: tags label: Tags items: 1

tags-wrap

spacing: tags label: Tags items: 14

tags-small-wrap

spacing: tags label: Tags items: 20

tags-long-member

spacing: tags label: Tags items: 3

tags-ja

spacing: tags label: タグ items: 4

tags-rtl

spacing: tags label: الوسوم direction: rtl items: 4

spacing: chips (12)

chips-links

spacing: chips label: Tags items: 4

chips-filters

spacing: chips label: Filters items: 5

chips-filters-wrap

spacing: chips label: Filters items: 12

chips-filters-small

spacing: chips label: Filters items: 4

chips-filters-disabled-member

spacing: chips label: Filters items: 3

chips-filters-multiple

spacing: chips label: Filters selection: multiple values: ["open","review"] items: 5

chips-filters-single

spacing: chips label: Sort by selection: single value: updated items: 4

chips-suggestions

spacing: chips label: Suggested fonts items: 5

chips-input

spacing: chips label: Recipients items: 3

chips-input-add

spacing: chips label: Recipients items: 4

chips-filters-rtl

spacing: chips label: عوامل التصفية direction: rtl items: 10

ltr-members-rtl

spacing: chips label: Tags direction: rtl items: 3

Generated from specs/tag-group.spec.json, tokens/comp/tag-group.tokens.json, design/tokens/

Guidelines

link

What a tag group is for

link

The set	Use
Static tags: an article’s categories, the values a setting can take, a row of statuses	A tag group with spacing="tags".
Tags that lead to each tag’s page	A tag group of chips with href. A tag is text and cannot be a link.
Filters above a list, suggestions under a field, items a person entered	A tag group of chips.
Filters that work as one control: one on at a time, or several, crossed with one Tab press	A tag group of filter chips with selection (below).
A row of toggle buttons that must stay on one line	A toolbar.
Two to four different actions	A button group.
One choice among several	A radio group, tabs or a segmented button.
Controls that need a visible label, a requirement and an error	A field group.
Entered values inside a field	The field’s own. A combobox lays out its chips itself.

Spacing

link

spacing says what the set holds, and decides two distances: between two members on a line, and between two lines.

• chips (the default) is for chips. A chip takes a press beyond its visible edge, up to a touch target. The lines stand far enough apart that each medium chip keeps that whole target, and where two chips’ areas would overlap they meet at the middle of the gap.
• tags is for static tags. The lines stand as close as the tags along a line, so a wrapped set reads as one block.

The default is the safe side. A set of tags left at chips only stands a little further apart. A set of chips set to tags still works, but its lines are closer than a touch target is high, and a debug build says so.

Small chips are for a dense place where the set stands on one line. On wrapped lines their touch targets meet between the lines before they reach full size. Use medium chips for a set that wraps on a touch screen.

A design system may add values of spacing.

Layout

link

• The members stand in the order you give them. The group never sorts them and never moves a selected chip forward.
• A member that does not fit goes whole to the next line. Nothing is cut, shrunk, hidden or scrolled, and there is no “+3 more”. To show fewer, give the group fewer members, and make the last one an action chip that shows the rest.
• One member wider than the group gets the group’s width and cuts its own label with an ellipsis.
• The set starts at the start edge. To place it at the end or in the middle of a row, place the group with the layout around it.
• Give every member the same size. Members of different sizes are centred on their line.
• A group with no member draws nothing and takes no space. A post with no tags needs no special case.

The label

link

label names the set for assistive technology: “Tags”, “Filters”. It is not drawn. Where the set needs a visible name, write your own heading or text before it, and still give label.

Selection

link

By default the group holds no value. Each filter chip holds its own selected, and each chip is its own Tab stop.

Set selection when the filters work as one control. Give each filter chip a value; the group then says which chips are on.

• selection="single": at most one chip is on, named by value. Switching a chip on switches the others off. Switching the chip that is on off leaves none on, and value is null, because each chip is a toggle.
• selection="multiple": any number are on, named by values.

When a person switches a chip, the group sets value or values and fires one change with detail.value or detail.values. The chip’s own change stops at the group. Setting value or values yourself switches the chips and fires nothing.

With a selection the set is one Tab stop: the chip that last had focus, otherwise the first chip that is on, otherwise the first chip. The arrow keys move between the chips the way they point, also in a right-to-left layout, and Home and End go to the first and the last. They switch nothing, and focus does not wrap from the last chip to the first. Space switches the focused chip.

One sort order at a time, and several filters

<tanrei-tag-group id="filters" label="Filters" selection="multiple" values="open">
  <tanrei-chip kind="filter" label="Open" value="open"></tanrei-chip>
  <tanrei-chip kind="filter" label="Assigned to me" value="assigned"></tanrei-chip>
  <tanrei-chip kind="filter" label="Needs review" value="review"></tanrei-chip>
</tanrei-tag-group>

<script type="module">
  document.querySelector('#filters').addEventListener('change', (event) => {
    // detail.values: the values of the chips that are now on, which the group already holds.
    applyFilters(event.detail.values);
  });
</script>

import { Chip, TagGroup } from '@tanrei/react';

<TagGroup label="Sort by" selection="single" value={order} onChange={(event) => setOrder(event.detail.value)}>
  <Chip kind="filter" label="Newest" value="newest" />
  <Chip kind="filter" label="Recently updated" value="updated" />
  <Chip kind="filter" label="Most comments" value="comments" />
</TagGroup>

A selection holds filter chips only. Other chips in the set, such as an “Add” chip or entered items, are reached with the same arrow keys and work as they always do. An entered item is still removed with Backspace or Delete, and the chip that then has focus becomes the set’s Tab stop.

When you take a filter chip away, the group leaves value and values as they are. Change them yourself if the filter should be gone too.

A choice that must always have exactly one answer, with no way to clear it, is a segmented button or a radio group.

Removing a chip

link

A chip asks to be removed and you remove it. If focus was on that chip or on its remove action, the group puts focus on the chip that followed, or on the one before when none follows. A person who removes several items in a row goes on from where they were.

A chip’s remove action is plain unless you set destructiveRemove on that chip, and the group does not change it. Set it only where removing loses something that cannot be put back in a step, such as an attachment; an applied filter or a search term comes back in one step.

Two things stay yours:

• When no chip is left to take focus, move focus to the control the set belongs to: the field that adds items, or the button that opens the filters. Otherwise the browser drops it.
• The group announces nothing. Where a removal must be heard, such as a filter removed far from the list it changes, report it in a live region or a snackbar.

Do

link

• Set spacing="tags" for a set of static tags.
• Give the set a label, in the language of the page.
• Keep one kind of member in a set. Entered items followed by one “Add” chip is the exception.

Don’t

link

• Don’t use a tag group for the actions of a dialog or a form. Use a button group.
• Don’t put anything but tags and chips in it. Other content is laid out, and reported in debug builds.
• Don’t restyle the members from the group. Change the group’s tokens in a layer instead.

Accessibility

link

Role

list

Labeling

label names the list ("Tags", "Filters"); it is not drawn. Each member is one list item and keeps its own name inside it: a tag its text, a chip its label, an input chip's remove action its removeLabel. A filter chip's state is its own pressed state, also while the group holds the selection: the chip then shows the group's selection. An empty group exposes nothing.

Minimum target

The hit area meets the minimum target size even when the visual size is smaller. minimum 32px · pointer 44px · spacing 8px · touch 48px

Keyboard

Keys	Action
Tab / Shift+Tab	While selection is none: moves focus to each chip of the set in turn, in the order given; an input chip is one stop, its remove action is not in the Tab order. While selection is single or multiple: the set is one stop — the chip that last had focus, else the first chip that is on, else the first chip (TGR-20). A set of tags has no stop.
Left Arrow / Right Arrow, Home / End	While selection is single or multiple: move focus to the chip drawn before or after (the way the arrow points, in a right-to-left layout too), or to the first or the last, without switching anything; focus does not wrap. Up and Down Arrow do nothing. While selection is none the group handles no key.
Enter, Space, Backspace / Delete	The focused chip's own keys, as the Chip says: Space switches a filter chip — and, while selection is single or multiple, changes the group's selection (TGR-19); Backspace or Delete removes an input chip. After a removal, focus is on the chip that followed, or on the one before where none follows (TGR-9).

Notes

• Not interactive by itself: the tag group never takes focus itself, and while selection is none it handles no key (TGR-6), so it has no target of its own to size and minimumTarget holds through its chips, each of which extends its own hit area (CHP-5). What the group owes them is room: gap and row-gap decide how much of each extended hit area a chip keeps beside and between its neighbours (TGR-5).
• Why a list, for tags and for chips alike: a list tells a person how many members there are and where they are among them, which is what a set of like things needs — four tags on an article, the third of nine filters. It holds static text, links and buttons equally, so one component needs no setting for its semantics.
• Why not a group: a group says that controls belong together and nothing more. It is what a button group is, whose two to four members are different actions; a tag group's members are of one kind and any number.
• Why not a list box, also while the group holds a selection: a list box is one control whose options hold the selection (aria-selected), and an option cannot hold a button — an input chip's remove action, or the chip's own button — inside it. React Aria's TagGroup exposes a selectable set as a grid, rows that carry aria-selected and the remove button in a cell; Tanrei's chip is a button whose pressed state already says whether it is on, which is how M3's filter chips and Carbon's selectable tags say it, so a selection keeps the list and each chip its pressed state. One choice among several that is not a filter is a radio group, tabs or a segmented button; a choice from a list is a select.
• Why one stop with arrow keys only with a selection: while selection is none each chip is its own Tab stop, as every Button of a button group is (CHP-23), and a set of links or of entered items is crossed by Tab. A set that holds a selection is one control to the person who uses it, as a segmented button's segments and Material's chip set are: one stop, the arrow keys inside it (TGR-20), focus not wrapping, as in the chip field (CHF-13). The list stays, so a screen reader still says how many chips there are and where one is among them.
• While selection is none the tag group does not make filter chips exclusive and holds no value: each filter chip is on or off by itself. With selection single the group puts one on at a time and a chip that is on can be switched off, leaving none, because each chip is a toggle; a choice that must always hold one value is a segmented button or a radio group. With multiple any number are on. The group names its chips by their value, as a segmented button names its segments, and its change carries value or values, as the segmented button's does (TGR-19).
• After the last member is removed the group is gone and cannot hold focus. The product moves focus to what the set belonged to (the field that adds items, the button that opens the filters); otherwise the platform drops it. The docs page says so with an example.
• Removing and selecting together: an input chip has no selected state (CHP-11), so in a set that holds a selection the entered items are reached by the arrow keys and removed by Backspace or Delete as before, and the filter chips are switched; the chip that receives focus after a removal becomes the set's stop (TGR-21). A filter chip that the product takes away leaves value and values as they were (TGR-17): the product, which took it away, changes them where it wants the filter gone.
• A removal is not announced by the group. Where it must be (a filter removed far from the list it changes), the product reports it in a live region or with a snackbar.
• A status among a set of tags never rests on color alone: each tag says it in words (TAG-11).
• A small chip is for dense places where a set stands on one line. On wrapped lines small chips are 24 high and 16 apart under the default system, so their touch targets meet between the lines at 40; a set of small chips that wraps on a touch screen wants medium chips.
• Text size: at 200% members grow and the set wraps onto more lines; nothing is cut by the group (TGR-12).
• Compose and React Native have no list role for an arbitrary layout: the group is a traversal group whose content description is label and whose collection information gives the count (Compose), or a labelled container (React Native), and each member keeps its own role.

Generated from specs/tag-group.spec.json, tokens/sys/measure.tokens.json

What the component handles

link

• The set is exposed as one list, named by label. Each member is one item of it: a tag is read as its text, a chip as its button or its link with its state, and an input chip with its remove action beside it.
• A list tells a person how many members there are and where they are among them: “list, 4 items”.
• The members are read and focused in the order given, in a right-to-left layout too.
• Without a selection, each chip is its own stop in the focus order, and an input chip one: Tab passes its remove action, and Backspace or Delete on the chip removes it. The group takes no focus and handles no key.
• With a selection, the set is one stop. The arrow keys, Home and End move between its chips, and each filter chip still says it is pressed or not. The group is still a list, so a screen reader still says how many chips there are.
• After a focused chip is removed, focus goes to the next chip, never to a remove action. With a selection, that chip becomes the set’s stop.
• An empty group exposes nothing: no empty list and no name.
• At 200% text the members grow and wrap onto more lines. Nothing is cut and nothing scrolls sideways.
• In forced colors the group draws nothing, as before. The members draw their own edges.
• In a right-to-left layout every line starts at the right.

How it is built on the web: the list is one element in the group’s shadow root, around the slot. The group writes role="listitem" on each member while it is in the group, and takes it back when the member leaves. A member that has a role of its own, or is a native element with a meaning of its own (a link, a button), keeps it and is not an item. Wrap such an element in a span.

Known gaps on the web:

• Before the element is defined the members are on the page in order, separated by the white space between them, without the gaps and without the list. A page that wants the layout from the first paint adds:

  tanrei-tag-group:not(:defined) {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    gap: var(--tanrei-comp-tag-group-row-gap-chips) var(--tanrei-comp-tag-group-gap-chips);
  }

What you need to do

link

• Give the group a label. The component supplies no words of its own.
• Give each input chip a removeLabel that names the item.
• With a selection, give each filter chip a value, unique in the set. A filter chip without one is left out of the selection, and a debug build says so.
• Remove a chip when it fires remove, and move focus yourself when the last one has gone.
• Say a status in each tag’s words. Color alone never says it.