Combobox

API reference and demos for Combobox.

Source

Import

import { Combobox } from "@flanksource/clicky-ui/components";

Demos

Default · Open in Storybook

Playground · Open in Storybook

Loading · Open in Storybook

The props table documents the component-specific surface. Standard DOM attributes inherited from React, such as className, event handlers, and accessibility attributes, may also be accepted when the component’s prop type extends a native element.

Props

Prop	Type	Default	Description
allowCustomValue	boolean	—	When false, the value is restricted to the provided options — typed text that does not match an option is discarded instead of committed. Defaults to true (freeform entry allowed).
ariaLabel	string	—	Accessible name for the input. Use when `label` is a non-string node (e.g. an icon) so the control still has a text name for screen readers; defaults to `label` when it is a string.
ariaRequired	boolean	—	Sets aria-required on the input. Separate from `required`, which governs whether the value can be cleared; a consumer announcing a mandatory field to assistive technology need not also remove the clear button.
className	string	—	Classes applied to the root wrapper.
describedBy	string	—	Id of the element describing the control (typically its validation message), wired through as aria-describedby.
disabled	boolean	—	Disables the input.
footer	ReactNode	—	Non-interactive content pinned below the option rows.
id	string	—	HTML id for the input element.
invalid	boolean	—	Marks the control as invalid: renders a destructive border and sets aria-invalid. Purely presentational — the consumer decides what invalid means (e.g. a value absent from the options in a strict picker).
label	ReactNode	—	Optional label rendered inline inside the control, before the input.
loading	boolean	—	Shows a loading indicator when options are being fetched.
menuWidth	number	—	Preferred popup width in pixels, constrained to the viewport. The control keeps its own width.
multiple	boolean	—	—
onChange*	(…) => …	—	—
onCreate	(…) => string | null	—	Converts a creatable option into the committed value. Returning null rejects the candidate. Defaults to the option's value.
onKeyDown	(…) => void	—	Called when a key is pressed in the input.
onNew	(…) => ComboboxOption | null	—	Converts unmatched text into a creatable option. Returning null rejects the text. The same option decorates a controlled unmatched single value.
onSearch	(…) => void	—	Optional async search invoked (debounced ~250ms) as the user types. The consumer fetches and feeds matching options back via the `options` prop.
options*	ComboboxOption[]	—	Available options, rendered in the order provided.
placeholder	string	—	Ghost text when no value is set.
prefix	ReactNode	—	Leading in-field adornment, rendered at the left edge of the input.
required	boolean	—	When true, the value cannot be cleared (the clear button is hidden).
searchPlacement	enum	—	Places the filter in the popup and uses a button for the closed control. Custom entries appear only when no options match; dismissal discards the search.
separators	string[]	—	Characters that commit the typed text as a value, alongside Enter — and that pasted text is split on (newlines always split too). For a list of short values that is usually typed or pasted comma-separated. Tags variant only; needs `allowCustomValue`.
size	enum	—	Overrides the input's height/padding/text size with an explicit size token (xs–xl). When unset, the input uses the global density tokens.
suffix	ReactNode	—	Trailing in-field adornment, rendered left of the clear/chevron controls.
title	string	—	Tooltip for the menu filter button.
triggerClassName	string	—	Button classes for the menu filter layout.
triggerContent	ReactNode	—	Replaces the closed caption when searchPlacement is menu.
tristate	boolean	—	—
value*	string | string[] | Record<string, ComboboxTriStateMode>	—	—
variant	enum	—	Renders selected values as wrapping removable pills instead of a summary. Renders each value as a pill carrying its mode (included / excluded) instead of the `+n -n` summary. The pill cycles include ↔ exclude on click and its close button returns the value to neutral.