Combobox - Docs - Artefact

Combobox

Forms

Smart auto-detect

Introduction

A widget that combines a text input with a listbox, allowing users to filter and select from a list of options.

Hydration

Tier 2 — smart auto-detect. A Combobox renders as static HTML and ships no client JS unless a behavioral signal is present. Pass interactive={true} to force hydration, or interactive={false} to force a static render.

It hydrates as an island when any of the following signals is present (or interactive={true} is set):

open (controlled open state)
inputValue (controlled input value)
onToggle
onInputChange
onItemSelect (item selection callback — select-only comboboxes hydrate on this)

`interactive` prop	Result
omitted, no signal	Static — no client JS
omitted, a signal present	Hydrates as an island
`true`	Hydrates as an island
`false`	Static — no client JS

All interactivity decisions in the library route through the shared shouldHydrate() helper in app/components/ui/island-utils.ts.

Usage

Framework

import { Combobox } from "../components/ui";

const items = [
  { label: "React", value: "react" },
  { label: "Solid", value: "solid" },
  { label: "Svelte", value: "svelte" },
  { label: "Vue", value: "vue" },
  { label: "Hono", value: "hono" },
];

export default function MyPage() {
  return (
    <Combobox
      interactive
      items={items}
      label="Framework"
      placeholder="Select a Framework"
      allowClear
    />
  );
}

CMS Page Builder

This component is available as a combobox block in the Page Builder (content/pages/*.json):

{
  "type": "combobox",
  "label": "Framework",
  "placeholder": "Select a Framework",
  "items": [
    { "label": "React", "value": "react" },
    { "label": "Hono", "value": "hono" }
  ]
}

Props

Prop	Type	Description
`items`	`ComboboxItem[]`	An array of items to display in the list.
`label`	`Child`	The label for the combobox.
`placeholder`	`string`	The placeholder text for the input.
`allowClear`	`boolean`	Whether to show a clear button in the input.
`interactive`	`boolean`	Forces hydration as an island.
`open`	`boolean`	Whether the combobox list is open (controlled).
`inputValue`	`string`	The current value of the input (controlled).
`onToggle`	`() => void`	Callback triggered when the list is toggled.
`onInputChange`	`(value: string) => void`	Callback triggered when the input value changes.
`onItemSelect`	`(value: string) => void`	Callback triggered when an item is selected.

ComboboxItem

Prop	Type	Description
`label`	`string`	The display text for the item.
`value`	`string`	The unique value for the item.
`disabled`	`boolean`	Whether the item is disabled.