import * as React from 'react';
import { Combobox } from 'gnome-ui/combobox';
import { ChevronDown, Check } from 'lucide-react';

const frameworks = ['React', 'Vue', 'Angular', 'Svelte', 'Ember', 'Solid', 'Next.js'];

export function ComboboxDefault() {
  return (
    <Combobox.Root className="relative w-72">
      <div className="flex h-10 w-full items-center justify-between rounded-xl border border-input bg-card px-3 text-sm text-foreground shadow-sm transition-colors focus-within:border-primary focus-within:outline focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-ring">
        <Combobox.Input 
          className="flex-1 bg-transparent outline-none placeholder:text-muted-foreground" 
          placeholder="Select a framework..." 
        />
        <Combobox.Trigger className="ml-2 shrink-0 text-muted-foreground hover:text-foreground">
          <Icons.ChevronDown className="size-4" />
        </Combobox.Trigger>
      </div>
      
      <Combobox.Portal>
        <Combobox.Positioner className="z-50 w-[var(--anchor-width)]" sideOffset={4}>
          <Combobox.Popup className="overflow-hidden rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md outline-none">
            <Combobox.List className="max-h-60 overflow-y-auto">
              <Combobox.Empty className="py-6 text-center text-sm text-muted-foreground">
                No results found.
              </Combobox.Empty>
              {frameworks.map((fw) => (
                <Combobox.Item 
                  key={fw} 
                  value={fw} 
                  className="relative flex w-full cursor-default select-none items-center rounded-md py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-primary data-[highlighted]:text-primary-foreground"
                >
                  <Combobox.ItemIndicator className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
                    <Icons.Check className="size-4" strokeWidth={3} />
                  </Combobox.ItemIndicator>
                  {fw}
                </Combobox.Item>
              ))}
            </Combobox.List>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox.Root>
  );
}

Anatomy

import { Combobox } from 'gnome-ui/combobox';

<Combobox.Root>
  <Combobox.Input />
  <Combobox.Trigger>
    <Combobox.Icon />
  </Combobox.Trigger>
  <Combobox.Portal>
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.List>
          <Combobox.Item>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        </Combobox.List>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Portal>
</Combobox.Root>

Examples

Multiple Selection with Chips

Combobox supports multiple selections. You can use the Combobox.Chips and Combobox.Chip components to render the selected values inside the input area.

import * as React from 'react';
import { Combobox } from 'gnome-ui/combobox';
import { Check, X } from 'lucide-react';

const frameworks = ['React', 'Vue', 'Angular', 'Svelte', 'Ember', 'Solid', 'Next.js'];

export function ComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>(['React', 'Vue']);

  return (
    <Combobox.Root multiple value={value} onValueChange={setValue} className="relative w-full max-w-md">
      <div className="flex min-h-10 w-full flex-wrap items-center gap-1.5 rounded-xl border border-input bg-card p-1.5 text-sm text-foreground shadow-sm transition-colors focus-within:border-primary focus-within:outline focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-ring">
        <Combobox.Chips className="flex flex-wrap items-center gap-1.5">
          {value.map((val) => (
            <Combobox.Chip 
              key={val} 
              value={val}
              className="flex items-center gap-1 rounded-md bg-secondary px-2 py-1 text-xs font-medium text-secondary-foreground"
            >
              {val}
              <Combobox.ChipRemove className="ml-1 rounded-full text-muted-foreground hover:bg-muted-foreground/20 hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring">
                <Icons.X className="size-3" />
              </Combobox.ChipRemove>
            </Combobox.Chip>
          ))}
        </Combobox.Chips>
        <Combobox.Input 
          className="flex-1 min-w-[120px] bg-transparent px-2 py-1 outline-none placeholder:text-muted-foreground" 
          placeholder="Add more..." 
        />
      </div>
      
      <Combobox.Portal>
        <Combobox.Positioner className="z-50 w-[var(--anchor-width)]" sideOffset={4}>
          <Combobox.Popup className="overflow-hidden rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md outline-none">
            <Combobox.List className="max-h-60 overflow-y-auto">
              <Combobox.Empty className="py-6 text-center text-sm text-muted-foreground">
                No more options.
              </Combobox.Empty>
              {frameworks.map((fw) => (
                <Combobox.Item 
                  key={fw} 
                  value={fw} 
                  className="relative flex w-full cursor-default select-none items-center rounded-md py-1.5 pl-8 pr-2 text-sm outline-none transition-colors data-[highlighted]:bg-primary data-[highlighted]:text-primary-foreground"
                >
                  <Combobox.ItemIndicator className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
                    <Icons.Check className="size-4" strokeWidth={3} />
                  </Combobox.ItemIndicator>
                  {fw}
                </Combobox.Item>
              ))}
            </Combobox.List>
          </Combobox.Popup>
        </Combobox.Positioner>
      </Combobox.Portal>
    </Combobox.Root>
  );
}

ComboboxArrow

Displays an element positioned against the anchor. Renders a <div> element.

API reference

Root

Groups all parts of the combobox. Doesn't render its own HTML element.

Root Props:

• 'pointer': the highlight changed due to pointer hovering.
• 'none': the highlight changed programmatically. | | onOpenChangeComplete | ((open: boolean) => void) | - | Event handler called after any animations complete when the popup is opened or closed. | | openOnInputClick | boolean | true | Whether the popup opens when clicking the input. | | virtualized | boolean | false | Whether the items are being externally virtualized. | | disabled | boolean | false | Whether the component should ignore user interaction. | | readOnly | boolean | false | Whether the user should be unable to choose a different option from the popup. | | required | boolean | false | Whether the user must choose a value before submitting a form. | | inputRef | Ref<HTMLInputElement> | - | A ref to the hidden input element. | | id | string | - | The id of the component. | | children | ReactNode | - | - |

Value

The current value of the combobox. Doesn't render its own HTML element.

Value Props:

Icon

An icon that indicates that the trigger button opens the popup. Renders a <span> element.

Icon Props:

Input

A text input to search for items in the list. Renders an <input> element.

Input Props:

Input Data Attributes:

Clear

Clears the value when clicked. Renders a <button> element.

Clear Props:

Clear Data Attributes:

Trigger

A button that opens the popup. Renders a <button> element.

Trigger Props:

Trigger Data Attributes:

Chips

A container for the chips in a multiselectable input. Renders a <div> element.

Chips Props:

Chip

An individual chip that represents a value in a multiselectable input. Renders a <div> element.

Chip Props:

ChipRemove

A button to remove a chip. Renders a <button> element.

ChipRemove Props:

List

A list container for the items. Renders a <div> element.

List Props:

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

Portal Props:

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

Backdrop Props:

Backdrop Data Attributes:

Positioner

Positions the popup against the trigger. Renders a <div> element.

Positioner Props:

• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | side | Side | 'bottom' | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. | | sideOffset | number \| OffsetFunction | 0 | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:* data.anchor: the dimensions of the anchor element with properties width and height.
• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | arrowPadding | number | 5 | Minimum distance to maintain between the arrow and the edges of the popup.Use it to prevent the arrow element from hanging out of the rounded corners of a popup. | | anchor | Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null | - | An element to position the popup against. By default, the popup will be positioned against the trigger. | | collisionAvoidance | CollisionAvoidance | - | Determines how to handle collisions when positioning the popup. | | collisionBoundary | Boundary | 'clipping-ancestors' | An element or a rectangle that delimits the area that the popup is confined to. | | collisionPadding | Padding | 5 | Additional space to maintain from the edge of the collision boundary. | | sticky | boolean | false | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. | | positionMethod | 'absolute' \| 'fixed' | 'absolute' | Determines which CSS position property to use. | | className | string \| ((state: Combobox.Positioner.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Combobox.Positioner.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Combobox.Positioner.State) => ReactElement) | - | Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render. |

Positioner Data Attributes:

Positioner CSS Variables:

Popup

A container for the list. Renders a <div> element.

Popup Props:

• true: Move focus based on the default behavior (first tabbable element or popup).
• RefObject: Move focus to the ref element.
• function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing. | | finalFocus | boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null) | - | Determines the element to focus when the popup is closed.* false: Do not move focus.
• true: Move focus based on the default behavior (trigger or previously focused element).
• RefObject: Move focus to the ref element.
• function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing. | | className | string \| ((state: Combobox.Popup.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Combobox.Popup.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Combobox.Popup.State) => ReactElement) | - | Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render. |

Popup Data Attributes:

Arrow

Displays an element positioned against the anchor. Renders a <div> element.

Arrow Props:

Arrow Data Attributes:

Status

Displays a status message whose content changes are announced politely to screen readers. Useful for conveying the status of an asynchronously loaded list. Renders a <div> element.

Status Props:

Empty

Renders its children only when the list is empty. Requires the items prop on the root component. Announces changes politely to screen readers. Renders a <div> element.

Empty Props:

Collection

Renders filtered list items. Doesn't render its own HTML element.If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it.

Collection Props:

Row

Displays a single row of items in a grid list. Enable grid on the root component to turn the listbox into a grid. Renders a <div> element.

Row Props:

Item

An individual item in the list. Renders a <div> element.

Item Props:

Item Data Attributes:

ItemIndicator

Indicates whether the item is selected. Renders a <span> element.

ItemIndicator Props:

Group

Groups related items with the corresponding label. Renders a <div> element.

Group Props:

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

Separator

A separator element accessible to screen readers. Renders a <div> element.

Separator Props:

useFilter

Matches items against a query using Intl.Collator for robust string matching. This hook is used when externally filtering items. Pass the result to the filter prop of <Combobox.Root>.

Input parameters

Accepts all Intl.CollatorOptions, plus the following options:

Props:

Return value

Return Value:

useFilteredItems

Returns the internally filtered items when called inside <Combobox.Root>.

Return value

Return Value: