TagSelector

TagSelector - A multi-select tag component with search, create, edit, delete, and reorder capabilities.

ConcreteTerrazzoAdd tags…

Usage

import { TagColor, TagData, TagSelector, TagSelectorContent, TagSelectorContextValue, TagSelectorItem, TagSelectorList, TagSelectorProps, TagSelectorSearch, TagSelectorTrigger, TagSelectorTriggerRenderProps, useTagSelectorContext } from "@instruments/materia-ui/compositions/tag-selector";

Best practices

The CRUD affordances are gated - onCreateTag/onEditTag/onDeleteTag/onReorder do nothing unless you also set the matching allowCreate/allowManage/allowReorder flag.
value/onChange carry the selected TagData[] and are required - TagSelector is controlled; supply the full option set via tags.
A custom trigger render-prop is passed to PopoverTrigger as render, so return a single element that forwards its ref/props (e.g. a Button).
Use singleSelect when only one tag may be chosen; for a fixed, non-editable list prefer Combobox/multi-Select and reserve TagSelector for managing the tag set itself.

Props

TagSelector

Prop	Type	Description
allowCreate	`boolean`	Allow creating new tags
allowManage	`boolean`	Allow editing/deleting tags
allowReorder	`boolean`	Allow reordering tags
className	`string`
colorPalette	`TagColor[]`	Available colours for the colour picker
coverTrigger	`boolean`	Whether the popover overlaps the trigger instead of appearing below it
disabled	`boolean`	Disabled state
emptyMessage	`string`	Empty state message
maxVisibleTags	`number`	Cap how many selected chips the trigger renders. When set and the selection exceeds it, only the first N chips show, followed by a `+N` overflow count pill. Undefined (default) renders every chip (wrapping or scrolling per `wrapTags`). Handy for fixed-width table cells.
onChange(required)	`(tags: TagData[]) => void`	Called when selection changes
onCreateTag	`(label: string, color?: TagColor) => Promise<TagData>`	Called when a new tag is created
onDeleteTag	`(id: string) => Promise<void>`	Called when a tag is deleted
onEditTag	`(id: string, newLabel: string, color?: TagColor) => Promise<void>`	Called when a tag is edited
onOpenChange	`(open: boolean) => void`	Called when open state changes
onReorder	`(tags: TagData[]) => void`	Called when tags are reordered
onSearch	`(query: string) => Promise<TagData[]>`	Called when tags list should be refetched (e.g., on search)
open	`boolean`	Controlled open state
reorderAnnouncements	`Announcements`	Override the drag-and-drop screen-reader announcements used while reordering tags. Follows
placeholder	`string`	Placeholder text
searchPlaceholder	`string`	Search input placeholder
showColorPicker	`boolean`	Show colour picker swatches when creating/editing tags
singleSelect	`boolean`	Single-select mode: only one tag can be selected at a time
size	`import("../../components/pill").PillSize`	Component size
tags	`TagData[]`	All available tags
trigger	`(props: TagSelectorTriggerRenderProps) => React.ReactElement`	Custom trigger render function. When provided, replaces the default trigger.
truncateChips	`boolean`	Opt-in per-chip truncation. Long labels ellipsise (CSS `truncate` + a max-width) instead of pushing the trigger/search row wider, keeping the `+N` overflow pill and search input visible. Default false = chips keep their natural width.
value(required)	`TagData[]`	Currently selected tags
wrapTags	`boolean`	Whether tags wrap (true) or scroll horizontally (false)

TagSelectorContent

Prop	Type	Default	Description
children(required)	`React.ReactNode`
className	`string`

TagSelectorItem

Prop	Type	Default	Description
selected(required)	`boolean`		Whether this tag is selected
tag(required)	`TagData`		The tag data

TagSelectorList

Prop	Type	Default	Description
className	`string`
emptyMessage	`string`		Custom empty state message

TagSelectorSearch

Prop	Type	Default	Description
className	`string`
placeholder	`string`		Placeholder text for search input

TagSelectorTrigger

Prop	Type	Default	Description
className	`string`
placeholder	`string`		Placeholder text when no tags selected

Also exports

typeTagColor
interfaceTagData
interfaceTagSelectorContextValue
interfaceTagSelectorProps
interfaceTagSelectorTriggerRenderProps
constuseTagSelectorContext

Composition

Builds on

Button, Dot, DropdownMenu, Flex, Icon, Input, Pill, Popover, ScrollArea, ScrollFade, Tag