Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Installation

Import Select primitives from @/components/kamod-ui/select.

Install PackagesTerminal
pnpm add @kamod-ch/ui

Copy 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 SetupTypeScript
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.

src/components/SelectExample.tsx14 lines
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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Disabled 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Scrollable 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Invalid 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 Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width
API reference

Props 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.

API reference
Your API, from source

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

Read each option with its owning component. The
marker identifies required fields verified in that declaration. A ? 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.
@kamod-ch/ui/select38.2 KB min · 9.2 KB gzipSignals: direct@preact/signals

Select

SelectProps

Select documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectProps

Configure children for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectProps

Configure class for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
defaultValue
stringSelectProps

Configure defaultValue for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
disabled
booleanSelectProps

Configure disabled for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
name
stringSelectProps

Configure name for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onValueChange
((value: string) => void)SelectProps

Configure onValueChange for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
required
booleanSelectProps

Configure required for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
value
stringSelectProps

Configure value for Select. Compare its accepted type with the Usage Guidance before supplying a value.

Default
null

SelectContent

SelectContentProps

SelectContent documented props
Prop / typeDescription
align
"start" | "center" | "end"SelectContentProps

Configure align for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"start"
children
ComponentChild[] | ComponentChildSelectContentProps

Configure children for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectContentProps

Configure class for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
forceMount
booleanSelectContentProps

Configure forceMount for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false
onKeyDown
KeyboardEventHandler<HTMLDivElement>SelectContentProps

Configure onKeyDown for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
portal
booleanSelectContentProps

Render in document.body and align to the trigger (default: inline under trigger).

Default
false
side
"bottom" | "top" | "right" | "left"SelectContentProps

Configure side for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"bottom"
sideOffset
numberSelectContentProps

Configure sideOffset for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
4
style
string | CSSProperties | SignalLike<string | CSSProperties | undefined>SelectContentProps

Configure style for SelectContent. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectGroup

SelectGroupProps

SelectGroup documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectGroupProps

Configure children for SelectGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectGroupProps

Configure class for SelectGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectItem

SelectItemProps

SelectItem documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectItemProps

Configure children for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectItemProps

Configure class for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
disabled
booleanSelectItemProps

Configure disabled for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
false
id
string | SignalLike<string | undefined>SelectItemProps

Configure id for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onClick
MouseEventHandler<HTMLDivElement>SelectItemProps

Configure onClick for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onFocus
FocusEventHandler<HTMLDivElement>SelectItemProps

Configure onFocus for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onKeyDown
KeyboardEventHandler<HTMLDivElement>SelectItemProps

Configure onKeyDown for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onMouseMove
MouseEventHandler<HTMLDivElement>SelectItemProps

Configure onMouseMove for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
value
stringSelectItemProps

Configure value for SelectItem. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectLabel

SelectLabelProps

SelectLabel documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectLabelProps

Configure children for SelectLabel. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectLabelProps

Configure class for SelectLabel. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectSearch

SelectSearchProps

SelectSearch documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>SelectSearchProps

Configure class for SelectSearch. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectSeparator

SelectSeparatorProps

SelectSeparator documented props
Prop / typeDescription
class
string | SignalLike<string | undefined>SelectSeparatorProps

Configure class for SelectSeparator. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectTrigger

SelectTriggerProps

SelectTrigger documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectTriggerProps

Configure children for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectTriggerProps

Configure class for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
disabled
boolean | SignalLike<boolean | undefined>SelectTriggerProps

Configure disabled for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onClick
MouseEventHandler<HTMLButtonElement>SelectTriggerProps

Configure onClick for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onKeyDown
KeyboardEventHandler<HTMLButtonElement>SelectTriggerProps

Configure onKeyDown for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
ref
Ref<HTMLButtonElement>SelectTriggerProps

Configure ref for SelectTrigger. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

SelectValue

SelectValueProps

SelectValue documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildSelectValueProps

Configure children for SelectValue. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>SelectValueProps

Configure class for SelectValue. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
placeholder
stringSelectValueProps

Configure placeholder for SelectValue. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"Select"

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 fields
SelectProps
Exported Source Declaration from Select.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 fields
SelectContentProps
Exported Source Declaration from SelectContent.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 field
SelectGroupProps
Exported Source Declaration from SelectGroup.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 fields
SelectItemProps
Exported Source Declaration from SelectItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectItemProps before adapting it.
Required fields
value

SelectLabel Props

1 declared field
SelectLabelProps
Exported Source Declaration from SelectLabel.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

Declaration
SelectSearchProps
Exported Source Declaration from SelectSearch.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of SelectSearchProps before adapting it.
SelectSeparatorProps
Exported Source Declaration from SelectSeparator.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 field
SelectTriggerProps
Exported Source Declaration from SelectTrigger.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 fields
SelectValueProps
Exported Source Declaration from SelectValue.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.

  1. Open, navigate past disabled options, select and reopen using only the keyboard.
  2. Confirm selected and highlighted options remain distinguishable in light, dark and high-contrast appearances.
  3. 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.

Take the Next Useful Step

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.