Forms & Input
Select
Select provides a modern Radix-style single-choice picker. Make the expected input clear before someone interacts, and keep the current value, help text and validation feedback connected. Import it from @/components/kamod-ui/select.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import Select primitives from @/components/kamod-ui/select.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Compose trigger, value, groups and content items to build accessible single-select dropdowns.
import { Select } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Select in Different Contexts, from the starting pattern to the compositions below. Begin with Basic Select, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Basic Select
Keep the Chosen Value Separate from Its Label. Compose a select trigger and option list for one choice from a known set. The trigger displays the selected label, while each option's stable value provides the data your application stores or submits.
Use stable option values, decide how an empty selection is represented and connect the change callback to the application state that will actually be submitted.
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@kamod-ch/ui";
export const Example = () => (
<Select defaultValue="preact" class="w-full max-w-sm">
<SelectTrigger>
<SelectValue placeholder="Select framework" />
</SelectTrigger>
<SelectContent>
<SelectItem value="react">React</SelectItem>
<SelectItem value="preact">Preact</SelectItem>
<SelectItem value="svelte">Svelte</SelectItem>
</SelectContent>
</Select>
);Groups and Separators
Make a Longer Collection Easier to Scan. Use group labels and separators to organize a longer select list into meaningful categories. This provides context for similar options without requiring every label to repeat the category name.
Keep group names short and consider Combobox when users need to search rather than inspect a long sequence manually.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDisabled Items
Preserve Context for Unavailable Choices. Mark unavailable options as disabled while retaining their place in the selection list. This preserves the shape of the option set and lets the surrounding form explain why some choices cannot currently be made.
Put relevant prerequisites nearby, and handle a previously selected value becoming unavailable rather than leaving the trigger and application state inconsistent.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthScrollable Content
Keep the Popup within a Manageable Height. Let the select content's maximum height constrain a long option list into a scrollable popup. The control can remain close to its trigger while readers move through more choices than fit on screen at once.
Test keyboard navigation into offscreen items and the longest labels, and consider searchable selection when scrolling no longer provides an efficient way to find the desired value.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInvalid State
Make the Correction Clear. Coordinate the surrounding Field with invalid ARIA attributes on the select's interactive control. The message should identify the problem with the chosen value, while the visual state directs attention to the field that needs correction.
Keep the field label visible, preserve the current value for review, and update the feedback when the selection is validated rather than using color as the only signal.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps and Data
Configure Select using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Select
SelectProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
defaultValue | Configure
|
disabled | Configure
|
name | Configure
|
onValueChange | Configure
|
required | Configure
|
value | Configure
|
SelectContent
SelectContentProps
| Prop / type | Description |
|---|---|
align | Configure
|
children | Configure
|
class | Configure
|
forceMount | Configure
|
onKeyDown | Configure
|
portal | Render in document.body and align to the trigger (default: inline under trigger).
|
side | Configure
|
sideOffset | Configure
|
style | Configure
|
SelectGroup
SelectGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
SelectItem
SelectItemProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
id | Configure
|
onClick | Configure
|
onFocus | Configure
|
onKeyDown | Configure
|
onMouseMove | Configure
|
value | Configure
|
SelectLabel
SelectLabelProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
SelectSearch
SelectSearchProps
| Prop / type | Description |
|---|---|
class | Configure
|
SelectSeparator
SelectSeparatorProps
| Prop / type | Description |
|---|---|
class | Configure
|
SelectTrigger
SelectTriggerProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
onClick | Configure
|
onKeyDown | Configure
|
ref | Configure
|
SelectValue
SelectValueProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
placeholder | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
Select Props
7 declared fieldsSelectPropsSelect.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectProps before adapting it.SelectContent Props
6 declared fieldsSelectContentPropsSelectContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectContentProps before adapting it.SelectGroup Props
1 declared fieldSelectGroupPropsSelectGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectGroupProps before adapting it.SelectItem Props
3 declared fieldsSelectItemPropsSelectItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectItemProps before adapting it.valueSelectLabel Props
1 declared fieldSelectLabelPropsSelectLabel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectLabelProps before adapting it.SelectSearch Props
DeclarationSelectSearchPropsSelectSearch.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectSearchProps before adapting it.SelectSeparator Props
DeclarationSelectSeparatorPropsSelectSeparator.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectSeparatorProps before adapting it.SelectTrigger Props
1 declared fieldSelectTriggerPropsSelectTrigger.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectTriggerProps before adapting it.SelectValue Props
2 declared fieldsSelectValuePropsSelectValue.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectValueProps before adapting it.Accessibility
Build the Complete Interaction, Including the Parts Outside Select. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the Live Preview, check the Props and Data Reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.
Built-in Behavior and Defaults
Select uses a button trigger and a listbox of options. The trigger exposes expanded state and the content ID; the listbox tracks its active option. Each SelectItem communicates selection and any disabled state.
Labels and Relationships
Give SelectTrigger a visible label through its ID or aria-labelledby. A placeholder communicates the absence of a value, but does not replace the field name. Keep option text self-contained so it makes sense while navigating the listbox.
Keyboard and Focus
The trigger opens with Arrow Up, Arrow Down, Enter or Space. In the list, arrows and Home/End move the active option; Enter or Space selects. Escape closes, and Tab exits according to the control's handler. Retain these behaviors when customizing content.
States and Integration Details
Do not add interactive buttons inside an option. Put aria-invalid and associated error text on the trigger when validating. Do not assume a custom select participates in native form submission exactly like NativeSelect; inspect the documented value integration.
Verify the Complete Interaction
Check Behavior as Well as Markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.
- Open, navigate past disabled options, select and reopen using only the keyboard.
- Confirm selected and highlighted options remain distinguishable in light, dark and high-contrast appearances.
- Read the field name, current choice and validation error without depending on a placeholder.
Recheck the result after changing Theme Tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the Component Source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.
For background, read the WAI-ARIA Authoring Guidance and Keyboard Interface Guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.