Selection and preferences

useSelect

Manages a fully custom select with native <select> fallback, ARIA listbox, typeahead character search, keyboard navigation, and external form integration.

Copy React example Select component

Live component preview · Astro

Explore Select

Try the component this hook connects to. The preview uses the Astro adapter; the React example below uses useSelect.

Framework

Region

Density

Surface

React usage

Import from @santi020k/lumen-react and spread the controller props onto the matching components.

import { Select } from '@santi020k/lumen-react'
import { useSelect } from '@santi020k/lumen-react'

export function CountrySelect() {
  const select = useSelect({
    options: ['United States', 'Canada', 'Mexico'],
    placeholder: 'Choose a country',
    onValueChange: (value) => console.log('Selected:', value)
  })

  return (
    <div {...select.rootProps}>
      <button {...select.triggerProps}>{select.triggerText}</button>
      <select {...select.nativeSelectProps} />
      <div {...select.listProps}>
        {select.options.map(option => (
          <button key={option.value} {...select.getOptionProps(option)}>
            {option.label}
          </button>
        ))}
      </div>
    </div>
  )
}

import { Select } from '@santi020k/lumen-react'
import { useSelect } from '@santi020k/lumen-react'

export function CountrySelect() {
  const select = useSelect({
    options: ['United States', 'Canada', 'Mexico'],
    placeholder: 'Choose a country',
    onValueChange: (value) => console.log('Selected:', value)
  })

  return (
    <div {...select.rootProps}>
      <button {...select.triggerProps}>{select.triggerText}</button>
      <select {...select.nativeSelectProps} />
      <div {...select.listProps}>
        {select.options.map(option => (
          <button key={option.value} {...select.getOptionProps(option)}>
            {option.label}
          </button>
        ))}
      </div>
    </div>
  )
}

Load @santi020k/lumen-react/styles.css once in your application. With React Server Components, put 'use client' at the top of the module that calls the hook. Follow the React setup guide for the framework boundary.

Options

Property	Type	Default	Description
options	Array<string \| SelectOption>	[]	Available options. Strings are converted to { label, value } objects.
defaultValue	string	""	Initial selected value.
value	string	-	Controlled selected value.
onValueChange	(value: string) => void	-	Callback fired when the selected value changes.
placeholder	string	-	Placeholder text shown when no option is selected.
disabled	boolean	false	Disable the select trigger.
required	boolean	false	Mark the hidden native select as required for form validation.
name	string	-	Name attribute for the hidden native select.
id	string	auto	Explicit id for the listbox.

Controller return values

Property	Type	Description
rootProps	LumenProps<"div">	Spread onto the select root wrapper.
triggerProps	LumenProps<"button">	Spread onto the trigger button. Includes keyboard navigation.
listProps	LumenProps<"div">	Spread onto the listbox container.
controlProps	LumenProps<"div">	Spread onto the visual control wrapper.
nativeSelectProps	LumenProps<"select">	Spread onto a hidden native <select> for form compatibility.
getOptionProps(option)	(option, props?) => LumenProps<"button">	Returns props for an option button.
selectedOption	SelectOption \| undefined	Currently selected option object.
triggerText	string	Display text for the trigger (selected label or placeholder).
value	string	Currently selected value.
options	SelectOption[]	Normalized options array.
open	boolean	Whether the listbox is open.
close	() => void	Close the listbox.
selectOption	(value: string) => void	Programmatically select an option by value.