Combobox

Combobox is the primitive for a filterable, single-value picker: searchable selects, command palettes, and autocomplete fields. It coordinates value state, input text, query filtering, item registration, positioning, and dismissal so your component only has to render the field, the listbox, and the items.

Reach for Combobox when a select needs type-to-filter behavior: an input narrows a registered list of items by text, the user picks one, and the chosen value drives the field. Combobox owns three pieces of state at once — the selected value, the input text, and the open state — and keeps them in sync, falling back to a forced selection so the field is never left in an invalid state.

Import

import { Combobox } from "@lattice-ui/combobox";

Anatomy

Compose the parts you need. Root, Portal, Content, and Item form the working picker. Use either Input (type-to-filter) or Trigger + Value (toggle and display) as the anchor, and Group, Label, and Separator to structure longer lists.

<Combobox.Root>
  <Combobox.Trigger>
    <Combobox.Value />
  </Combobox.Trigger>
  <Combobox.Input />
  <Combobox.Portal>
    <Combobox.Content>
      <Combobox.Label />
      <Combobox.Group>
        <Combobox.Item value="..." />
      </Combobox.Group>
      <Combobox.Separator />
      <Combobox.Item value="..." />
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>

Example

A controlled combobox with a filtering input. Typing narrows the list; selecting an item sets the value and syncs the input.

import { useState } from "@rbxts/react";
import { Combobox } from "@lattice-ui/combobox";

const WORLDS = ["Aurora", "Basalt", "Cinder", "Driftwood", "Ember"];

export function WorldPicker() {
  const [value, setValue] = useState<string>();

  return (
    <Combobox.Root value={value} onValueChange={setValue}>
      <Combobox.Input placeholder="Search worlds" />

      <Combobox.Portal>
        <Combobox.Content sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} />
            <Combobox.Label asChild>
              <textlabel Text="Worlds" />
            </Combobox.Label>
            {WORLDS.map((world) => (
              <Combobox.Item key={world} value={world}>
                <textbutton Text={world} />
              </Combobox.Item>
            ))}
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}

How it behaves

Open state

Combobox.Root is controllable. Pass open and onOpenChange to control the listbox, or defaultOpen to run uncontrolled (defaults to closed). Combobox.Trigger toggles the list on activation (and on Return/Space), and typing in Combobox.Input opens it automatically. Selecting an item closes the list.

Value and input state

The selected value and the input text are separate, independently controllable pieces of state. Selecting an item sets the value and syncs the input to that item’s display text. Typing in the input updates the query (and opens the list) without changing the value until a selection is made; when the list closes, the input is re-synced from the current value so the field always shows the selected item. Set required to force a selection: while the list is open, Combobox keeps a valid enabled item selected, falling back to the first enabled item rather than leaving the value empty.

Combobox.Value displays the selected item’s text, resolved from the item registry, or its placeholder when nothing is selected. disabled blocks all state changes; readOnly blocks input edits but still allows selection through items.

Filtering

Combobox.Item declares a value and an optional textValue (the text matched and displayed; defaults to value). The root’s filterFn decides whether each item matches the current query — the default does a case-insensitive substring match. Items that do not match are hidden and made non-interactive, so the list shows only what fits the query. Provide your own filterFn for fuzzy matching, token search, or locale-aware comparison.

Positioning

Combobox.Content is positioned by the popper foundation against the active anchor — the input when present, otherwise the trigger. It flips to the opposite side on collision. Tune it with placement ("top" | "bottom" | "left" | "right", default "bottom"), sideOffset (gap from the anchor, default 0), alignOffset (shift along the cross axis, default 0), and collisionPadding (minimum distance from the screen edge, default 8).

Dismissal

Combobox.Content participates in dismissable-layer behavior and is always non-modal, so the rest of the UI stays interactive while the list is open. The trigger and input are registered as inside refs, so interacting with them does not dismiss the list. Any other outside press closes it. Use onPointerDownOutside and onInteractOutside to observe or veto those interactions before the list closes.

Motion and presence

Combobox.Content runs a default popper-aware canvas-group reveal/exit recipe that animates from the resolved placement, so the list animates in and out without extra setup. Override it with transition, and pass forceMount to keep the content mounted through its exit animation (useful when you drive motion yourself or need the node to persist).

API reference

Combobox.Root

Combobox.Input

Combobox.Trigger

Combobox.Value

Combobox.Portal

Combobox.Content

Combobox.Item

Combobox.Group

Combobox.Label

Combobox.Separator

Related

• Positioning with popper
• Portals and layers
• Controlled state
• Presence and motion
• asChild composition