Scoped Label Picker

ProNew

A label picker where labels named scope::value are mutually exclusive within a scope, so choosing priority::high replaces priority::low. Use this when labels describe one attribute with several possible values.

Customize

Derived from this item’s props table, because it declares no controls of its own. This item has no standalone playground, so changes update the code, the share link and the AI prompt.

separator

Guide and examples

When to use it

Use it for issue and ticket labels where an item has exactly one priority, one status or one severity but any number of free labels, and a second priority must never be possible.

Do not use it when labels never conflict. Use a plain multi-select.

Installation

This item is part of tealmac UI Pro

The source for this item installs with a Pro licence key. Log in with your key to see the install command, or read the Pro setup page.

Props

Prop	Type	Default	Description
`labels`	`string[]`	-	Every label. A name with `::` is scoped, e.g. `priority::high`.
`value`	`string[]`	-	Chosen labels (controlled).
`defaultValue`	`string[]`	`[]`	Initial labels.
`onValueChange`	`(labels: string[]) => void`	-	Runs on every change.
`separator`	`string`	`::`	What splits scope from value.

Accessibility

Scoped labels are grouped under their scope and the heading ends with (pick one); ungrouped labels are under Labels.
Options carry aria-checked; the list is aria-multiselectable.
When a pick replaces another a role="status" line says so.
Chips show scope: value, so the scope is readable without colour.

Testing

The pattern ships with a Testing Library test (scoped-label-picker.test.tsx) that covers replacing within a scope, removing, free labels staying multiple and the announcement.

Guide and examples

When to use it

Use it for issue and ticket labels where an item has exactly one priority, one status or one severity but any number of free labels, and a second priority must never be possible.

Do not use it when labels never conflict. Use a plain multi-select.

Installation

This item is part of tealmac UI Pro

The source for this item installs with a Pro licence key. Log in with your key to see the install command, or read the Pro setup page.

Props

Prop	Type	Default	Description
`labels`	`string[]`	-	Every label. A name with `::` is scoped, e.g. `priority::high`.
`value`	`string[]`	-	Chosen labels (controlled).
`defaultValue`	`string[]`	`[]`	Initial labels.
`onValueChange`	`(labels: string[]) => void`	-	Runs on every change.
`separator`	`string`	`::`	What splits scope from value.

Accessibility

Scoped labels are grouped under their scope and the heading ends with (pick one); ungrouped labels are under Labels.
Options carry aria-checked; the list is aria-multiselectable.
When a pick replaces another a role="status" line says so.
Chips show scope: value, so the scope is readable without colour.

Testing

The pattern ships with a Testing Library test (scoped-label-picker.test.tsx) that covers replacing within a scope, removing, free labels staying multiple and the announcement.