--- name: select-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Select for non-search selection with Zag.js collection behavior, hidden form select, trigger, value text, clear trigger, item groups, item indicators, validation status, size, and multiple mode. metadata: component_version: "1.5.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/select" contributor_sources: "libs/ui/src/molecules/select.tsx libs/ui/src/tokens/components/molecules/_select.css libs/ui/stories/molecules/select.stories.tsx libs/ui/src/molecules/select.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Select Usage Use Select for choosing from known options. Use Combobox when the user needs search/filter text input. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Select`. **Use it when** - One (or several) values from a known list of about 6–15 options: status, category, country with few entries, sort order. **Use something else when** | Need | Use instead | | --- | --- | | 2–5 options that fit on screen | RadioGroup | | Long list needing search | Combobox | | Hierarchical values | CascadeSelect | | Commands | Menu | | Colour swatches | ColorSelect | **Do** - Label with the noun; placeholder `Select a ` only when there is no sensible default. - Order options predictably (logical order, else alphabetical); keep `Other` last. - Show disabled options only when the reason is visible (e.g. `Out of stock`). **Don't** - Use a Select for yes/no. - Trigger navigation or actions on change. **Copy and states** - Options in sentence case, parallel grammar; the same option names as the status vocabulary. **Behaviour (from the UX spec)** - Opening the list and moving through options never commits; closing without choosing keeps the previous value. - Clearing a required Select leaves a missing value that validation reports, never an "empty" option that looks chosen. - Select prunes values missing from `items`. To show a saved value as unavailable, keep that item in `items` as `disabled`, say why in the helper text and block submitting until it is resolved — don't silently drop or replace it. - With remote options, show waiting, no matches and error separately, and discard responses older than the latest query. - Don't use `size="xs"` for app form fields; sm/md/lg are canonical. **Figma → code** | Figma | Code | | --- | --- | | `size=xs…lg` | `size` | | `state=error` / `success` / `warning` | `validateStatus` | | `state=disabled` | `disabled` | | `state=readonly` | `readOnly` | | `required=true` | `required` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Select → UX guidelines*. ## Setup ```tsx ``` Supported props: ```text items: { label, value, disabled, displayValue }[] size: xs | sm | md | lg validateStatus: default | error | success | warning value/defaultValue: string[] multiple, disabled, required, readOnly, closeOnSelect, loopFocus name, form, onValueChange, onOpenChange, onHighlightChange ``` ## Core Patterns ### Keep Select anatomy intact Use Label, Control, Trigger, ValueText, Positioner, Content, Item, ItemText, and ItemIndicator. ### Use array values Zag Select values are arrays, including single-select values. ### Use StatusText part for help/error Use `Select.StatusText` with `validateStatus`, not external paragraphs. ## Common Mistakes ### HIGH Native select Wrong: ```tsx ``` Correct: ```tsx import { SelectTemplate } from "@techsio/ui-kit/templates/select" ``` Source: libs/ui/src/molecules/select.tsx ### HIGH String value Wrong: ```tsx