--- title: "Tag group" description: "Lays out a set of tags or chips in lines that wrap, spaced for what it holds, and exposes the set as one named list. The members stay what they are, and after a chip is removed focus goes on to the next." url: "https://tanrei.chnotchy.com/components/tag-group/" last_updated: 2026-10-23T21:17:12.000Z --- # Tag group > Lays out a set of tags or chips in lines that wrap, spaced for what it holds, and exposes the set as one named list. The members stay what they are, and after a chip is removed focus goes on to the next. ## Overview A [tag](https://tanrei.chnotchy.com/components/tag/) and a [chip](https://tanrei.chnotchy.com/components/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 ``. The other platforms have not implemented it yet. ### Usage **Web** ```html ``` **React** ```tsx import { Chip, TagGroup } from '@tanrei/react'; {recipients.map((person) => ( remove(person.id)} /> ))} ``` ## Specs - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/tag-group/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/tag-group.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/tag-group`). - React: `TagGroup` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-tag-group` | lagging | | SwiftUI | `TanreiTagGroup` | planned | | Jetpack Compose | `TanreiTagGroup` | planned | | Flutter | `TanreiTagGroup` | planned | | React Native | `TagGroup` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | | `selection` (prop) | `selection` | `selectionMode` | `selectionMode` | `selectionMode` | `selectionMode` | | `value` (prop) | `value` | `selection` | `selectedValue` | `selectedValue` | `value` | | `values` (prop) | `values` | `selection` | `selectedValues` | `selectedValues` | `values` | | `change` (event) | `change` | `selection` | `onSelectionChange` | `onSelectionChanged` | `onSelectionChange` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `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. - `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. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `spacing` | `enum`: `tags`, `chips` | `"chips"` | `spacing` | 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` | `""` | `label` | 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` | `enum`: `none`, `single`, `multiple` | `"none"` | `selection` | 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` | — | `value` | 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` | `` | `values` | 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). | ### Item: `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. It is a Tag. Names: Web `tanrei-tag`, SwiftUI `TanreiTag`, Jetpack Compose `TanreiTag`, Flutter `TanreiTag`, React Native `Tag`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `label` | `string` | `""` | `label` | Its text, as the Tag's label. | | `variant` | `enum`: `tonal`, `outlined`, `filled` | `"tonal"` | `variant` | Its look, as the Tag's variant. | | `status` | `enum`: `default`, `info`, `warning`, `error`, `success` | `"default"` | `status` | What it reports, as the Tag's status. | | `size` | `enum`: `small`, `medium` | `"medium"` | `size` | 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. | ### Item: `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. It is a Chip. Names: Web `tanrei-chip`, SwiftUI `TanreiChip`, Jetpack Compose `TanreiChip`, Flutter `TanreiChip`, React Native `Chip`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `kind` | `enum`: `action`, `filter`, `input` | `"action"` | `kind` | What it does, as the Chip's kind. | | `label` | `string` | `""` | `label` | Its text and accessible name, as the Chip's label. | | `size` | `enum`: `small`, `medium` | `"medium"` | `size` | Its height, as the Chip's size. Give every member of a group the same size. | | `selected` | `boolean` | `false` | `selected` | 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` | `""` | `value` | 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` | `disabled` | As the Chip's disabled: one chip of a set may be disabled by itself. | | `href` | `string` | `""` | `href` | The destination of an action chip, as the Chip's href: it makes the chip a link. | | `removeLabel` | `string` | `""` | `remove-label` | 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). | ### States `enabled` ### Accessibility - 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 size: yes | 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 or 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). | - 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. ### Behaviour Requirements in EARS form, each with its stable id. - **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. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.tag-group.…` → `--tanrei-comp-tag-group-…`). #### `tanrei.comp.tag-group` | Token | Type | Value | | --- | --- | --- | | `comp.tag-group.gap.tags` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.tag-group.gap.chips` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.tag-group.row-gap.tags` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.tag-group.row-gap.chips` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.tag-group.motion.move-duration` | `duration` | `{tanrei.sys.motion.role.selection.travel}` | | `comp.tag-group.motion.move-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.spatial}` | ## Guidelines ### What a tag group is for | 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](https://tanrei.chnotchy.com/components/toolbar/). | | Two to four different actions | A [button group](https://tanrei.chnotchy.com/components/button-group/). | | One choice among several | A [radio group](https://tanrei.chnotchy.com/components/radio-group/), [tabs](https://tanrei.chnotchy.com/components/tabs/) or a [segmented button](https://tanrei.chnotchy.com/components/segmented-button/). | | Controls that need a visible label, a requirement and an error | A [field group](https://tanrei.chnotchy.com/components/field-group/). | | Entered values inside a field | The field’s own. A [combobox](https://tanrei.chnotchy.com/components/combobox/) lays out its chips itself. | ### Spacing `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 - 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 `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 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. **Web** ```html ``` **React** ```tsx import { Chip, TagGroup } from '@tanrei/react'; setOrder(event.detail.value)}> ``` 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](https://tanrei.chnotchy.com/components/segmented-button/) or a [radio group](https://tanrei.chnotchy.com/components/radio-group/). ### Removing a chip 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](https://tanrei.chnotchy.com/components/snackbar/). ### Do - 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 - 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 ### What the component handles - 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: ```css 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 - 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.