Token

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Token, TokenIntent, TokenSize, announceTokenRemoval, shouldRemoveLastTokenOnBackspace from @prepared911/ui/token.

Prop	Type	Default
`label`	`LocalizedMessage \| DisplayValue`	required
`intent`	`TokenIntent`	`Neutral`
`size`	`TokenSize`	`Large`
`icon`	`Glyph` (not with `avatar`)	;
`avatar`	`{ src?: string; fallback: AvatarName }` (not `icon`)	;
`onRemove`	`(details: TokenRemoveDetails) => void`	;
`removeLabel`	`LocalizedMessage` (required with `onRemove`)	;
`removedAnnouncement`	`LocalizedMessage` (required with `onRemove`)	;
`removeButtonRef`	ref to the remove `button` (with `onRemove`)	;
`selected`	`boolean`	;
`defaultSelected`	`boolean`	;
`onSelectedChange`	`(selected, details: ChangeDetails) => void`	;
`disabled`	`boolean`	`false`
`id`	`string`	;
`aria-describedby`	`string`	;
`className`	`string`	;
`ref`	ref to the shell `span`	;

aria-describedby sits on the toggle button when the token is selectable, so the description is read when the toggle takes focus; otherwise it sits on the shell. data-* attributes pass through to the shell, except the reserved design-system state names. Token takes no style, role, children, tabIndex, aria-label or other on* handler.

TokenIntent: Neutral, Informative, Success, Warning, Destructive. TokenSize: Small, Medium, Large.

Removal details

onRemove receives ChangeDetails<ChangeReason.ItemPress>. details.event is the click or the keydown, details.source is the shell, and the change is cancelable: details.cancel() keeps the token's announcement from firing. A press that changes the selection reports ChangeReason.ItemPress too.

Helpers

Export	Use
`shouldRemoveLastTokenOnBackspace(event)`	In a composer entry's `onKeyDown`: true when Backspace should remove the last token
`announceTokenRemoval(message, node?)`	Polite announcement for a removal the composer performs itself, in `node`'s owner document

Anatomy

The shell is a span with no role. It holds a label part (a span, or a button with aria-pressed when selectable) and the remove Button as siblings. Without onRemove and selection a token is a static label with no control.

Props

Name	Type	Default	Description
`label`	`TokenLabel`	—	Visible label. It is the token's name; meaning lives in this text, not in color.
`aria-describedby`	`string`	—	Id of the element that describes the token. Set on the toggle `button` when selectable, otherwise on the shell.
`avatar`	`TokenAvatar`	—	Decorative avatar before the label. The label stays the name.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`defaultSelected`	`boolean`	—	Initial selected state when uncontrolled.
`disabled`	`boolean`	—	Inert state. Disables the selection button and the remove button, and ignores Backspace and Delete.
`icon`	`Glyph`	—	Decorative glyph before the label. It is `aria-hidden`; the label stays the name.
`id`	`string`	—	Element id of the shell.
`intent`	`TokenIntent`	—	Status or neutral intent for shell paint and label color. Defaults to {@link TokenIntent.Neutral}.
`onRemove`	`((details: TokenRemoveDetails) => void)`	—	Called when the person removes the token with the remove button or with Backspace or Delete. The consumer removes the token from its own state and decides where focus goes next; the token that held focus unmounts. @param details - Change metadata; `event` is the click or key event, and `cancel()` keeps the token and the announcement
`onSelectedChange`	`((selected: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a press changes the selection. @param selected - Next selected state @param details - Change metadata; cancel to keep the previous state
`ref`	`Ref<HTMLSpanElement>`	—	Ref to the shell `span`.
`removeButtonRef`	`Ref<HTMLButtonElement>`	—	Ref to the remove Button. A consumer that moves focus after a removal keeps the Button of the token it moves to, so it never has to search the shell.
`removedAnnouncement`	`LocalizedMessage`	—	Announced politely after a removal that was not canceled, for example "Unit 12 removed".
`removeLabel`	`LocalizedMessage`	—	Accessible name of the remove button. Name the subject, for example "Remove Unit 12", not just "Remove".
`selected`	`boolean`	—	Whether the token is selected (controlled).
`size`	`TokenSize`	—	Height from the shared control heights. Defaults to {@link TokenSize.Large}.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Token / Usage

Token / Accessibility

On this page

Token

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import Token, TokenIntent, TokenSize, announceTokenRemoval, shouldRemoveLastTokenOnBackspace from @prepared911/ui/token.

Prop	Type	Default
`label`	`LocalizedMessage \| DisplayValue`	required
`intent`	`TokenIntent`	`Neutral`
`size`	`TokenSize`	`Large`
`icon`	`Glyph` (not with `avatar`)	;
`avatar`	`{ src?: string; fallback: AvatarName }` (not `icon`)	;
`onRemove`	`(details: TokenRemoveDetails) => void`	;
`removeLabel`	`LocalizedMessage` (required with `onRemove`)	;
`removedAnnouncement`	`LocalizedMessage` (required with `onRemove`)	;
`removeButtonRef`	ref to the remove `button` (with `onRemove`)	;
`selected`	`boolean`	;
`defaultSelected`	`boolean`	;
`onSelectedChange`	`(selected, details: ChangeDetails) => void`	;
`disabled`	`boolean`	`false`
`id`	`string`	;
`aria-describedby`	`string`	;
`className`	`string`	;
`ref`	ref to the shell `span`	;

TokenIntent: Neutral, Informative, Success, Warning, Destructive. TokenSize: Small, Medium, Large.

Removal details

Helpers

Export	Use
`shouldRemoveLastTokenOnBackspace(event)`	In a composer entry's `onKeyDown`: true when Backspace should remove the last token
`announceTokenRemoval(message, node?)`	Polite announcement for a removal the composer performs itself, in `node`'s owner document

Anatomy

Props

Name	Type	Default	Description
`label`	`TokenLabel`	—	Visible label. It is the token's name; meaning lives in this text, not in color.
`aria-describedby`	`string`	—	Id of the element that describes the token. Set on the toggle `button` when selectable, otherwise on the shell.
`avatar`	`TokenAvatar`	—	Decorative avatar before the label. The label stays the name.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`defaultSelected`	`boolean`	—	Initial selected state when uncontrolled.
`disabled`	`boolean`	—	Inert state. Disables the selection button and the remove button, and ignores Backspace and Delete.
`icon`	`Glyph`	—	Decorative glyph before the label. It is `aria-hidden`; the label stays the name.
`id`	`string`	—	Element id of the shell.
`intent`	`TokenIntent`	—	Status or neutral intent for shell paint and label color. Defaults to {@link TokenIntent.Neutral}.
`onRemove`	`((details: TokenRemoveDetails) => void)`	—	Called when the person removes the token with the remove button or with Backspace or Delete. The consumer removes the token from its own state and decides where focus goes next; the token that held focus unmounts. @param details - Change metadata; `event` is the click or key event, and `cancel()` keeps the token and the announcement
`onSelectedChange`	`((selected: boolean, details: ChangeDetails<ChangeReason>) => void)`	—	Called when a press changes the selection. @param selected - Next selected state @param details - Change metadata; cancel to keep the previous state
`ref`	`Ref<HTMLSpanElement>`	—	Ref to the shell `span`.
`removeButtonRef`	`Ref<HTMLButtonElement>`	—	Ref to the remove Button. A consumer that moves focus after a removal keeps the Button of the token it moves to, so it never has to search the shell.
`removedAnnouncement`	`LocalizedMessage`	—	Announced politely after a removal that was not canceled, for example "Unit 12 removed".
`removeLabel`	`LocalizedMessage`	—	Accessible name of the remove button. Name the subject, for example "Remove Unit 12", not just "Remove".
`selected`	`boolean`	—	Whether the token is selected (controlled).
`size`	`TokenSize`	—	Height from the shared control heights. Defaults to {@link TokenSize.Large}.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Token / Usage

Token / Accessibility

On this page