🚧 This documentation is a work in progress. Coming from @studs/react? See our Migration Guide.

Combobox

A searchable dropdown that combines an input with a list of selectable options.

ComboBox provides an autocomplete or command palette interface where users can type to filter and search through options. It's ideal for selecting from large lists where scrolling would be impractical. The component combines the functionality of a text input with a dropdown menu, offering type-ahead search and keyboard navigation.

Example

"use client"

import { useState } from "react"
import {
  ComboBox,
  ComboBoxContent,
  ComboBoxEmpty,
  ComboBoxInput,
  ComboBoxItem,
  ComboBoxItemGroup,
  ComboBoxList,
  ComboBoxTrigger,
} from "@strongtie/design-system/combobox"

const frameworks = [
  { value: "next", label: "Next.js" },
  { value: "react", label: "React" },
  { value: "remix", label: "Remix" },
  { value: "astro", label: "Astro" },
  { value: "vue", label: "Vue" },
  { value: "svelte", label: "Svelte" },
]

export function ComboboxDefault() {
  const [value, setValue] = useState("")

  return (
    <ComboBox
      value={value}
      onValueChange={setValue}
      placeholder="Select framework..."
    >
      <ComboBoxTrigger />
      <ComboBoxContent className="w-50 p-0">
        <ComboBoxInput placeholder="Search framework..." />
        <ComboBoxList>
          <ComboBoxEmpty>No framework found.</ComboBoxEmpty>
          <ComboBoxItemGroup>
            {frameworks.map((framework) => (
              <ComboBoxItem key={framework.value} value={framework.value}>
                {framework.label}
              </ComboBoxItem>
            ))}
          </ComboBoxItemGroup>
        </ComboBoxList>
      </ComboBoxContent>
    </ComboBox>
  )
}

Installation


npm install @strongtie/design-system

import { Combobox } from "@strongtie/design-system/combobox"

Components

This module exports the following components:

ComboBox
ComboBoxTrigger
ComboBoxTriggerInput
ComboBoxContent
ComboBoxInput
ComboBoxList
ComboBoxEmpty
ComboBoxItemGroup
ComboBoxItem

Props

`<ComboBox>`

Prop	Type	Default
`disabled`	`boolean`	-
`onValueChange`	`((arg: string) => void)`	-
`placeholder`	`string`	-
`value`	`string`	-

`<ComboBoxTriggerInput>`

Prop	Type	Default	Description
`onValueChange`	`((search: string) => void)`	-	Event handler called when the search value changes.
`value`	`string`	-	Optional controlled state for the value of the search input.

`<ComboBoxInput>`

Prop	Type	Default	Description
`onValueChange`	`((search: string) => void)`	-	Event handler called when the search value changes.
`value`	`string`	-	Optional controlled state for the value of the search input.

`<ComboBoxList>`

Prop	Type	Default	Description
`label`	`string`	-	Accessible label for this List of suggestions. Not shown visibly.

`<ComboBoxItemGroup>`

Prop	Type	Default	Description
`forceMount`	`boolean`	-	Whether this group is forcibly rendered regardless of filtering.
`heading`	`ReactNode`	-	Optional heading to render for this group.
`value`	`string`	-	If no heading is provided, you must provide a value that is unique for this group.

`<ComboBoxItem>`

Prop	Type	Default	Description
`disabled`	`boolean`	-	Whether this item is currently disabled.
`forceMount`	`boolean`	-	Whether this item is forcibly rendered regardless of filtering.
`keywords`	`string[]`	-	Optional keywords to match against when filtering.
`onSelect`	`((value: string) => void)`	-	Event handler for when this item is selected, either via click or keyboard selection.
`value`	`string`	-	A unique value for this item. If no value is provided, it will be inferred from `children` or the rendered `textContent`. If your `textContent` changes between renders, you must provide a stable, unique `value`.

Examples

"use client"

import { useState } from "react"
import {
  ComboBox,
  ComboBoxContent,
  ComboBoxEmpty,
  ComboBoxInput,
  ComboBoxItem,
  ComboBoxItemGroup,
  ComboBoxList,
  ComboBoxTrigger,
} from "@strongtie/design-system/combobox"

const frameworks = [
  { value: "next", label: "Next.js" },
  { value: "react", label: "React" },
  { value: "remix", label: "Remix" },
  { value: "astro", label: "Astro" },
  { value: "vue", label: "Vue" },
  { value: "svelte", label: "Svelte" },
]

export function ComboboxDefault() {
  const [value, setValue] = useState("")

  return (
    <ComboBox
      value={value}
      onValueChange={setValue}
      placeholder="Select framework..."
    >
      <ComboBoxTrigger />
      <ComboBoxContent className="w-50 p-0">
        <ComboBoxInput placeholder="Search framework..." />
        <ComboBoxList>
          <ComboBoxEmpty>No framework found.</ComboBoxEmpty>
          <ComboBoxItemGroup>
            {frameworks.map((framework) => (
              <ComboBoxItem key={framework.value} value={framework.value}>
                {framework.label}
              </ComboBoxItem>
            ))}
          </ComboBoxItemGroup>
        </ComboBoxList>
      </ComboBoxContent>
    </ComboBox>
  )
}

With Inline Search

"use client"

import { useState } from "react"
import {
  ComboBox,
  ComboBoxContent,
  ComboBoxEmpty,
  ComboBoxItem,
  ComboBoxItemGroup,
  ComboBoxList,
  ComboBoxTriggerInput,
} from "@strongtie/design-system/combobox"

const frameworks = [
  { value: "next.js", label: "Next.js" },
  { value: "sveltekit", label: "SvelteKit" },
  { value: "nuxt.js", label: "Nuxt.js" },
  { value: "remix", label: "Remix" },
  { value: "astro", label: "Astro" },
]

export function ComboboxWithInlineSearch() {
  const [value, setValue] = useState("")

  return (
    <ComboBox
      value={value}
      onValueChange={setValue}
      placeholder="Type to search..."
    >
      <ComboBoxTriggerInput
        placeholder="Search framework..."
        className="w-50"
      />
      <ComboBoxContent
        className="w-50 p-0"
        onOpenAutoFocus={(e) => e.preventDefault()}
      >
        <ComboBoxList>
          <ComboBoxEmpty>No framework found.</ComboBoxEmpty>
          <ComboBoxItemGroup>
            {frameworks.map((framework) => (
              <ComboBoxItem key={framework.value} value={framework.value}>
                {framework.label}
              </ComboBoxItem>
            ))}
          </ComboBoxItemGroup>
        </ComboBoxList>
      </ComboBoxContent>
    </ComboBox>
  )
}

Styling

Components can be styled using the className prop. The design system uses Tailwind CSS for styling.

Classes

CSS classes used by this component:

combobox-content
combobox-empty
combobox-input
combobox-item
combobox-item-group
combobox-list
combobox-trigger
combobox-trigger-input

Accessibility

Ensure proper accessibility attributes are added when implementing this component.

Collapsible Command

On This Page

Example Installation Components Props <ComboBox><ComboBoxTriggerInput><ComboBoxInput><ComboBoxList><ComboBoxItemGroup><ComboBoxItem>Examples With Inline Search Styling Classes Accessibility

Contribute