Combobox

Autocomplete input with a list of suggestions.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products}>
      <ComboboxInput placeholder="Select a product" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Composition

Simple

A single-line input and a flat list (see Basic).

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem

With chips

Multi-select with multiple, chips, and a chips input (see Multiple).

Combobox
├── ComboboxChips
│   ├── ComboboxValue
│   │   └── ComboboxChip
│   └── ComboboxChipsInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem

With groups and collection

Nested items per group using ComboboxCollection inside each ComboboxGroup, with a separator between groups (see Groups).

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxCollection
        │       ├── ComboboxItem
        │       └── ComboboxItem
        ├── ComboboxSeparator
        └── ComboboxGroup
            ├── ComboboxLabel
            └── ComboboxCollection
                ├── ComboboxItem
                └── ComboboxItem

Basic

A simple combobox with a list of products.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products}>
      <ComboboxInput placeholder="Select a product" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Multiple

A combobox with multiple selection using multiple and ComboboxChips.

Code

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
} from "@falcon/ui-kit";
import { useRef } from "react";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  const anchor = useRef<HTMLDivElement | null>(null);

  return (
    <Combobox
      multiple
      autoHighlight
      items={products}
      defaultValue={[products[0]]}
    >
      <ComboboxChips ref={anchor} className="tw:w-full tw:max-w-xs">
        <ComboboxValue>
          {(values) => (
            <>
              {values.map((value: string) => (
                <ComboboxChip key={value}>{value}</ComboboxChip>
              ))}
              <ComboboxChipsInput />
            </>
          )}
        </ComboboxValue>
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Clear Button

Use the showClear prop to show a clear button.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products} defaultValue={products[0]}>
      <ComboboxInput placeholder="Select a product" showClear />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Groups

Use ComboboxGroup and ComboboxSeparator to group items.

Code

import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxSeparator,
} from "@falcon/ui-kit";

const timezones = [
  {
    value: "Americas",
    items: [
      "(GMT-5) New York",
      "(GMT-8) Los Angeles",
      "(GMT-6) Chicago",
      "(GMT-5) Toronto",
      "(GMT-8) Vancouver",
      "(GMT-3) São Paulo",
    ],
  },
  {
    value: "Europe",
    items: [
      "(GMT+0) London",
      "(GMT+1) Paris",
      "(GMT+1) Berlin",
      "(GMT+1) Rome",
      "(GMT+1) Madrid",
      "(GMT+1) Amsterdam",
    ],
  },
  {
    value: "Asia/Pacific",
    items: [
      "(GMT+9) Tokyo",
      "(GMT+8) Shanghai",
      "(GMT+8) Singapore",
      "(GMT+4) Dubai",
      "(GMT+11) Sydney",
      "(GMT+9) Seoul",
    ],
  },
] as const;

export function Example() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone" />
      <ComboboxContent>
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group, index) => (
            <ComboboxGroup key={group.value} items={group.items}>
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
              {index < timezones.length - 1 && <ComboboxSeparator />}
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Custom Items

You can render a custom component inside ComboboxItem.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  Item,
  ItemContent,
  ItemDescription,
  ItemTitle,
} from "@falcon/ui-kit";

const countries = [
  { code: "", value: "", continent: "", label: "Select country" },
  {
    code: "ar",
    value: "argentina",
    label: "Argentina",
    continent: "South America",
  },
  { code: "au", value: "australia", label: "Australia", continent: "Oceania" },
  { code: "br", value: "brazil", label: "Brazil", continent: "South America" },
  { code: "ca", value: "canada", label: "Canada", continent: "North America" },
  { code: "cn", value: "china", label: "China", continent: "Asia" },
  {
    code: "co",
    value: "colombia",
    label: "Colombia",
    continent: "South America",
  },
  { code: "eg", value: "egypt", label: "Egypt", continent: "Africa" },
  { code: "fr", value: "france", label: "France", continent: "Europe" },
  { code: "de", value: "germany", label: "Germany", continent: "Europe" },
  { code: "it", value: "italy", label: "Italy", continent: "Europe" },
  { code: "jp", value: "japan", label: "Japan", continent: "Asia" },
  { code: "ke", value: "kenya", label: "Kenya", continent: "Africa" },
  { code: "mx", value: "mexico", label: "Mexico", continent: "North America" },
  {
    code: "nz",
    value: "new-zealand",
    label: "New Zealand",
    continent: "Oceania",
  },
  { code: "ng", value: "nigeria", label: "Nigeria", continent: "Africa" },
  {
    code: "za",
    value: "south-africa",
    label: "South Africa",
    continent: "Africa",
  },
  { code: "kr", value: "south-korea", label: "South Korea", continent: "Asia" },
  {
    code: "gb",
    value: "united-kingdom",
    label: "United Kingdom",
    continent: "Europe",
  },
  {
    code: "us",
    value: "united-states",
    label: "United States",
    continent: "North America",
  },
];

export function Example() {
  return (
    <Combobox
      items={countries.filter((country) => country.code !== "")}
      itemToStringValue={(country: (typeof countries)[number]) => country.label}
    >
      <ComboboxInput placeholder="Search countries..." />
      <ComboboxContent>
        <ComboboxEmpty>No countries found.</ComboboxEmpty>
        <ComboboxList>
          {(country) => (
            <ComboboxItem key={country.code} value={country}>
              <Item size="xs" className="tw:p-0">
                <ItemContent>
                  <ItemTitle className="tw:whitespace-nowrap">
                    {country.label}
                  </ItemTitle>
                  <ItemDescription>
                    {country.continent} ({country.code})
                  </ItemDescription>
                </ItemContent>
              </Item>
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Invalid

Use the aria-invalid prop to make the combobox invalid.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products}>
      <ComboboxInput placeholder="Select a product" aria-invalid="true" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Disabled

Use the disabled prop to disable the combobox.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products}>
      <ComboboxInput placeholder="Select a product" disabled />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Auto Highlight

Use the autoHighlight prop to automatically highlight the first item on filter.

Code

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@falcon/ui-kit";

const products = [
  "Corn seed",
  "Soybean seed",
  "Starter fertilizer",
  "Potash",
  "Urea",
] as const;

export function Example() {
  return (
    <Combobox items={products} autoHighlight>
      <ComboboxInput placeholder="Select a product" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

Popup

You can trigger the combobox from a button or any other component by using the render prop. Move the ComboboxInput inside the ComboboxContent.

Code

import {
  Button,
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxTrigger,
  ComboboxValue,
} from "@falcon/ui-kit";

const countries = [
  { code: "", value: "", continent: "", label: "Select country" },
  {
    code: "ar",
    value: "argentina",
    label: "Argentina",
    continent: "South America",
  },
  { code: "au", value: "australia", label: "Australia", continent: "Oceania" },
  { code: "br", value: "brazil", label: "Brazil", continent: "South America" },
  { code: "ca", value: "canada", label: "Canada", continent: "North America" },
  { code: "cn", value: "china", label: "China", continent: "Asia" },
  {
    code: "co",
    value: "colombia",
    label: "Colombia",
    continent: "South America",
  },
  { code: "eg", value: "egypt", label: "Egypt", continent: "Africa" },
  { code: "fr", value: "france", label: "France", continent: "Europe" },
  { code: "de", value: "germany", label: "Germany", continent: "Europe" },
  { code: "it", value: "italy", label: "Italy", continent: "Europe" },
  { code: "jp", value: "japan", label: "Japan", continent: "Asia" },
  { code: "ke", value: "kenya", label: "Kenya", continent: "Africa" },
  { code: "mx", value: "mexico", label: "Mexico", continent: "North America" },
  {
    code: "nz",
    value: "new-zealand",
    label: "New Zealand",
    continent: "Oceania",
  },
  { code: "ng", value: "nigeria", label: "Nigeria", continent: "Africa" },
  {
    code: "za",
    value: "south-africa",
    label: "South Africa",
    continent: "Africa",
  },
  { code: "kr", value: "south-korea", label: "South Korea", continent: "Asia" },
  {
    code: "gb",
    value: "united-kingdom",
    label: "United Kingdom",
    continent: "Europe",
  },
  {
    code: "us",
    value: "united-states",
    label: "United States",
    continent: "North America",
  },
];

export function Example() {
  return (
    <>
      <Combobox items={countries} defaultValue={countries[0]}>
        <ComboboxTrigger
          render={
            <Button
              variant="outline"
              className="tw:w-64 tw:justify-between tw:font-normal"
            />
          }
        >
          <ComboboxValue />
        </ComboboxTrigger>
        <ComboboxContent>
          <ComboboxInput showTrigger={false} placeholder="Search" />
          <ComboboxEmpty>No items found.</ComboboxEmpty>
          <ComboboxList>
            {(item) => (
              <ComboboxItem key={item.code} value={item}>
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </>
  );
}

Input Group

You can add an addon to the combobox by using the InputGroupAddon component inside the ComboboxInput.

Code

import {
  Combobox,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  GlobeIcon,
  InputGroupAddon,
} from "@falcon/ui-kit";

const timezones = [
  {
    value: "Americas",
    items: [
      "(GMT-5) New York",
      "(GMT-8) Los Angeles",
      "(GMT-6) Chicago",
      "(GMT-5) Toronto",
      "(GMT-8) Vancouver",
      "(GMT-3) São Paulo",
    ],
  },
  {
    value: "Europe",
    items: [
      "(GMT+0) London",
      "(GMT+1) Paris",
      "(GMT+1) Berlin",
      "(GMT+1) Rome",
      "(GMT+1) Madrid",
      "(GMT+1) Amsterdam",
    ],
  },
  {
    value: "Asia/Pacific",
    items: [
      "(GMT+9) Tokyo",
      "(GMT+8) Shanghai",
      "(GMT+8) Singapore",
      "(GMT+4) Dubai",
      "(GMT+11) Sydney",
      "(GMT+9) Seoul",
    ],
  },
] as const;

export function Example() {
  return (
    <Combobox items={timezones}>
      <ComboboxInput placeholder="Select a timezone">
        <InputGroupAddon>
          <GlobeIcon />
        </InputGroupAddon>
      </ComboboxInput>
      <ComboboxContent alignOffset={-28} className="tw:w-60">
        <ComboboxEmpty>No timezones found.</ComboboxEmpty>
        <ComboboxList>
          {(group) => (
            <ComboboxGroup key={group.value} items={group.items}>
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(item) => (
                  <ComboboxItem key={item} value={item}>
                    {item}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  );
}

API

Combobox

Provides shared state for a filterable input and predefined selectable items without rendering an element. Accepts supported root props; items may be objects with extra fields, and { value, label } items use label for display and value for form submission. There is no imperative actions API; control the popup with open/onOpenChange.

Props

autoComplete

autoComplete?: string

Provides a hint to the browser for autofill.

autoHighlight

autoHighlight?: boolean

Whether the first matching item is highlighted automatically while filtering.

children

children?: React.ReactNode

defaultInputValue

defaultInputValue?: string | number | readonly string[]

The uncontrolled input value when the combobox is initially rendered.

defaultOpen

defaultOpen?: boolean

Whether the popup is initially open. Use open to control the popup.

defaultValue

defaultValue?: ComboboxValueType<Value, Multiple> | null

The uncontrolled selected value when the combobox is initially rendered. Use value to control it.

disabled

disabled?: boolean

Whether the component should ignore user interaction.

filter

filter?: ((itemValue: Value, query: string, itemToString?: ((itemValue: Value) => string) | undefined) => boolean) | null

Filters items against the input query. Set to null to disable filtering.

filteredItems

filteredItems?: readonly any[] | readonly Group<any>[]

Items to render instead of internally filtered items.

form

form?: string

Identifies the form that owns the internal input.

grid

grid?: boolean

Whether list items are presented in a grid layout for arrow-key navigation.

highlightItemOnHover

highlightItemOnHover?: boolean

Whether moving the pointer over an item highlights it.

id

id?: string

The ID applied to the component.

inline

inline?: boolean

Whether the list is rendered inline rather than in the component popup.

inputRef

inputRef?: React.Ref<HTMLInputElement>

A ref to the hidden input element used for form submission.

inputValue

inputValue?: string | number | readonly string[]

The input value. Use when controlling the filter query.

isItemEqualToValue

isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean)

Compares an item value with the selected value. Defaults to Object.is.

items

items?: readonly any[] | readonly Group<any>[]

Items displayed in the list, optionally grouped.

itemToStringLabel

itemToStringLabel?: ((itemValue: Value) => string)

Converts object item values to the label displayed in the input.

itemToStringValue

itemToStringValue?: ((itemValue: Value) => string)

Converts object item values to the form value.

limit

limit?: number

The maximum number of items to display.

locale

locale?: Intl.LocalesArgument

The locale used for string comparison.

loopFocus

loopFocus?: boolean

Whether arrow-key navigation wraps between the input and list boundaries.

modal

modal?: boolean

Whether the open popup blocks outside interaction.

multiple

multiple?: Multiple

Whether multiple items can be selected.

name

name?: string

Identifies the field when a form is submitted.

onInputValueChange

onInputValueChange?: ((inputValue: string, eventDetails: ComboboxPrimitive.Root.ChangeEventDetails) => void)

Called when the input value changes.

onItemHighlighted

onItemHighlighted?: ((highlightedValue: Value | undefined, eventDetails: ComboboxPrimitive.Root.HighlightEventDetails) => void)

Called when an item is highlighted or unhighlighted.

onOpenChange

onOpenChange?: ((open: boolean, eventDetails: ComboboxPrimitive.Root.ChangeEventDetails) => void)

Called when the popup opens or closes.

onOpenChangeComplete

onOpenChangeComplete?: ((open: boolean) => void)

Called after opening or closing animations finish.

onValueChange

onValueChange?: ((value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ComboboxPrimitive.Root.ChangeEventDetails) => void)

Called when the selected value changes.

open

open?: boolean

Whether the popup is open. Use when controlling the popup.

openOnInputClick

openOnInputClick?: boolean

Whether clicking the input opens the popup.

readOnly

readOnly?: boolean

Whether the user can change the selected value.

required

required?: boolean

Whether choosing a value is required before form submission.

value

value?: ComboboxValueType<Value, Multiple> | null

The selected value. Use when controlling the combobox.

virtualized

virtualized?: boolean

Whether the list items are externally virtualized.

ComboboxChip

Renders a selected multiselect value in a <div>. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxChipState>

Replaces the rendered chip or composes it with another component.

showRemove

showRemove?: boolean = true

Whether to show the remove button.

style

style?: React.CSSProperties | ((state: ComboboxChipState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxChips

Renders a <div> container for multiselect chips. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxChipsState>

Replaces the rendered chip container or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxChipsState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxChipsInput

Renders a multiselect filter <input>. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

disabled

disabled?: boolean

Whether the component should ignore user interaction.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxInputState>

Replaces the rendered input or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxInputState) => React.CSSProperties | undefined)

Style applied to the input, or a function that returns a style from component state.

ComboboxCollection

Renders filtered items without adding an element.

Props

children

children: (item: any, index: number) => React.ReactNode

Renders each filtered item. Use a function child on ComboboxList for flat lists.

ComboboxContent

Renders a portalled, positioned <div> popup. render can replace the popup element.

Props

align

align?: Align = "start"

How the popup is aligned relative to its anchor.

alignOffset

alignOffset?: number | OffsetFunction = 0

Additional offset along the alignment axis in pixels.

anchor

anchor?: Element | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null

The element the popup is positioned against.

className

className?: string

CSS class applied to the popup.

finalFocus

finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null)

Determines the element to focus when the popup closes.

initialFocus

initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null)

Determines the element to focus when the popup opens.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxPopupState>

Replaces the rendered popup or composes it with another component.

side

side?: Side = "bottom"

Which side of the anchor to place the popup against.

sideOffset

sideOffset?: number | OffsetFunction = 6

Distance between the anchor and popup in pixels.

style

style?: React.CSSProperties | ((state: ComboboxPopupState) => React.CSSProperties | undefined)

Style applied to the popup, or a function that returns a style from component state.

ComboboxEmpty

Renders an empty-state announcement in a <div>. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxEmptyState>

Replaces the rendered empty state or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxEmptyState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxGroup

Renders a <div> that groups related items and their label. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

items

items?: readonly any[]

Items rendered within this group by child ComboboxCollection components.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupState>

Replaces the rendered group or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxGroupState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxInput

Renders an input-group wrapper around an <input> with optional clear and trigger controls. render can replace the input element.

Props

className

className?: string

CSS class applied to the input group.

disabled

disabled?: boolean

Whether the component should ignore user interaction.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxInputState>

Replaces the rendered input or composes it with another component.

showClear

showClear?: boolean

Whether to show a button that clears the selected value.

showTrigger

showTrigger?: boolean = true

Whether to show a button that opens the popup.

style

style?: React.CSSProperties | ((state: ComboboxInputState) => React.CSSProperties | undefined)

Style applied to the input, or a function that returns a style from component state.

ComboboxItem

Renders a selectable <div> item. render can replace the element.

Props

children

children?: React.ReactNode

The item contents.

className

className?: string

CSS class applied to the element.

disabled

disabled?: boolean

Whether the component should ignore user interaction.

index

index?: number

The item index, used to avoid calculating it from the DOM.

nativeButton

nativeButton?: boolean

Whether a custom render element is a native button.

onClick

onClick?: ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)

Called when the item is selected with the pointer or keyboard.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxItemState>

Replaces the rendered item or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxItemState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

value

value?: any

A unique value that identifies this item.

ComboboxLabel

Renders a <div> label associated with its group. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxGroupLabelState>

Replaces the rendered label or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxGroupLabelState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxList

Renders the item list in a <div>. render can replace the element.

Props

children

children?: React.ReactNode | ((item: any, index: number) => React.ReactNode)

List content, or a function that renders each item.

className

className?: string

CSS class applied to the element.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxListState>

Replaces the rendered list or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxListState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxSeparator

Renders an accessible <div> separator. render can replace the element.

Props

className

className?: string

CSS class applied to the element.

orientation

orientation?: Orientation

The separator orientation.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>

Replaces the rendered separator or composes it with another component.

style

style?: React.CSSProperties | ((state: SeparatorState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxTrigger

Opens the popup. Renders a <button> and render can replace the element.

Props

className

className?: string

CSS class applied to the element.

disabled

disabled?: boolean

Whether the component should ignore user interaction.

nativeButton

nativeButton?: boolean

Whether a custom render element is a native button.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ComboboxTriggerState>

Replaces the rendered element or composes it with another component.

style

style?: React.CSSProperties | ((state: ComboboxTriggerState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style from component state.

ComboboxValue

Renders the selected value without adding an element.

Props

children

children?: React.ReactNode | ((selectedValue: any) => React.ReactNode)

The current selected value, or a function that renders it.

placeholder

placeholder?: React.ReactNode

Displayed when no value is selected.