Use select options

React hook that filters static options or debounces API-backed combobox searches.

Installation

bash

pnpm dlx shadcn@latest add @cs/use-select-options

Usage

tsx

import { useSelectOptions } from "@/hooks/cs/use-select-options"

tsx

const { displayedOptions, search } = useSelectOptions({
  options: [{ id: "cz", name: "Czechia" }, { id: "de", name: "Germany" }],
  selected: [],
})

API Reference

SelectOption

Option shape accepted by useSelectOptions.

tsx

type SelectOption = {
	id: TValue
	name?: string
}

SelectFetchOptions

Configuration for requesting filtered options from an API route.

tsx

type SelectFetchOptions = {
	/** /api/combobox/path */
	path: string
	params?: Record<string, string>
	type?: "number" | "string"
}

useSelectOptions

Filters static options or debounces API-backed option searches for a combobox. Remote endpoints receive query and a JSON-encoded selected query parameter, and must return ActionResult with an option array in data.

Props

Name	Type	Default	Description
apiPath	string	"/api/combobox"	Base URL prepended to the configured remote endpoint path.
debounceMs	number	600	Delay in milliseconds before a remote search is requested.
fetchOptions	SelectFetchOptions	-	Remote endpoint configuration used to load matching options.
getOptionSearchText	(option: TOption) => string	-	Returns searchable text for a static option.
options	TOption[]	-	Static options to filter when no remote endpoint is configured.
selected *	TValue[]	-	Values that must remain available among remote search results.

Dependencies

@base-ui/react @cs/action-result @cs/status-is @cs/toast