Combobox

A searchable dropdown (autocomplete) that lets users filter and select from a list of options with full keyboard navigation and accessibility support.

1
---
2
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox class="w-[200px]">
6
  <ComboboxInput placeholder="Select framework..." showClear />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxEmpty>No results found.</ComboboxEmpty>
10
      <ComboboxItem value="astro">Astro</ComboboxItem>
11
      <ComboboxItem value="next">Next.js</ComboboxItem>
12
      <ComboboxItem value="nuxt">Nuxt</ComboboxItem>
13
      <ComboboxItem value="remix">Remix</ComboboxItem>
14
      <ComboboxItem value="svelte">SvelteKit</ComboboxItem>
15
    </ComboboxList>
16
  </ComboboxContent>
17
</Combobox>

Installation

bunx bejamas add combobox

npx bejamas add combobox

pnpm dlx bejamas add combobox

yarn dlx bejamas add combobox

Usage

1
---
2
import {
3
  Combobox,
4
  ComboboxInput,
5
  ComboboxContent,
6
  ComboboxList,
7
  ComboboxItem,
8
  ComboboxEmpty,
9
  ComboboxGroup,
10
  ComboboxLabel,
11
  ComboboxSeparator,
12
} from '@bejamas/ui/components/combobox';
13
---
14

15
<Combobox name="framework">
16
  <ComboboxInput placeholder="Select framework..." />
17
  <ComboboxContent>
18
    <ComboboxList>
19
      <ComboboxEmpty>No results found.</ComboboxEmpty>
20
      <ComboboxItem value="astro">Astro</ComboboxItem>
21
      <ComboboxItem value="next">Next.js</ComboboxItem>
22
    </ComboboxList>
23
  </ComboboxContent>
24
</Combobox>

Examples

Clear Button

Use the showClear prop to show a clear button in the input.

1
---
2
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox class="w-[200px]">
6
  <ComboboxInput placeholder="Select framework..." showClear />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxEmpty>No results found.</ComboboxEmpty>
10
      <ComboboxItem value="astro">Astro</ComboboxItem>
11
      <ComboboxItem value="next">Next.js</ComboboxItem>
12
      <ComboboxItem value="nuxt">Nuxt</ComboboxItem>
13
      <ComboboxItem value="remix">Remix</ComboboxItem>
14
    </ComboboxList>
15
  </ComboboxContent>
16
</Combobox>

Sizing

Use the size prop on ComboboxInput to match button/input sizing.

1
---
2
import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<div class="grid w-full max-w-sm gap-3">
6
  <Combobox>
7
    <ComboboxInput size="sm" placeholder="Small (h-8)" />
8
    <ComboboxContent>
9
      <ComboboxList>
10
        <ComboboxItem value="astro-sm">Astro</ComboboxItem>
11
        <ComboboxItem value="next-sm">Next.js</ComboboxItem>
12
      </ComboboxList>
13
    </ComboboxContent>
14
  </Combobox>
15
  <Combobox>
16
    <ComboboxInput placeholder="Default (h-9)" />
17
    <ComboboxContent>
18
      <ComboboxList>
19
        <ComboboxItem value="astro-default">Astro</ComboboxItem>
20
        <ComboboxItem value="next-default">Next.js</ComboboxItem>
21
      </ComboboxList>
22
    </ComboboxContent>
23
  </Combobox>
24
  <Combobox>
25
    <ComboboxInput size="lg" placeholder="Large (h-10)" />
26
    <ComboboxContent>
27
      <ComboboxList>
28
        <ComboboxItem value="astro-lg">Astro</ComboboxItem>
29
        <ComboboxItem value="next-lg">Next.js</ComboboxItem>
30
      </ComboboxList>
31
    </ComboboxContent>
32
  </Combobox>
33
</div>

Groups

Use the ComboboxGroup and ComboboxLabel to group items and add a label to the group.

1
---
2
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList, ComboboxSeparator } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox class="w-[200px]">
6
  <ComboboxInput placeholder="Select framework..." />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxEmpty>No results found.</ComboboxEmpty>
10
      <ComboboxGroup>
11
        <ComboboxLabel>Frontend</ComboboxLabel>
12
        <ComboboxItem value="astro">Astro</ComboboxItem>
13
        <ComboboxItem value="next">Next.js</ComboboxItem>
14
        <ComboboxItem value="nuxt">Nuxt</ComboboxItem>
15
      </ComboboxGroup>
16
      <ComboboxSeparator />
17
      <ComboboxGroup>
18
        <ComboboxLabel>Backend</ComboboxLabel>
19
        <ComboboxItem value="express">Express</ComboboxItem>
20
        <ComboboxItem value="hono">Hono</ComboboxItem>
21
      </ComboboxGroup>
22
    </ComboboxList>
23
  </ComboboxContent>
24
</Combobox>

Invalid

Use the aria-invalid="true" attribute on the ComboboxInput to mark the combobox as invalid.

1
---
2
import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox class="w-[200px]">
6
  <ComboboxInput placeholder="Select framework..." aria-invalid="true" />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxItem value="astro">Astro</ComboboxItem>
10
      <ComboboxItem value="next">Next.js</ComboboxItem>
11
    </ComboboxList>
12
  </ComboboxContent>
13
</Combobox>

Disabled

Use the disabled prop to disable the combobox.

1
---
2
import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox disabled class="w-[200px]">
6
  <ComboboxInput placeholder="Select framework..." disabled />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxItem value="astro">Astro</ComboboxItem>
10
      <ComboboxItem value="next">Next.js</ComboboxItem>
11
    </ComboboxList>
12
  </ComboboxContent>
13
</Combobox>

Auto Highlight

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

1
---
2
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox autoHighlight class="w-[200px]">
6
  <ComboboxInput placeholder="Start typing..." />
7
  <ComboboxContent>
8
    <ComboboxList>
9
      <ComboboxEmpty>No results found.</ComboboxEmpty>
10
      <ComboboxItem value="astro">Astro</ComboboxItem>
11
      <ComboboxItem value="next">Next.js</ComboboxItem>
12
      <ComboboxItem value="nuxt">Nuxt</ComboboxItem>
13
      <ComboboxItem value="remix">Remix</ComboboxItem>
14
    </ComboboxList>
15
  </ComboboxContent>
16
</Combobox>

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

1
---
2
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList, ComboboxTrigger, ComboboxValue } from '@bejamas/ui/components/combobox';
3
---
4

5
<Combobox class="w-[200px]">
6
  <ComboboxTrigger>
7
    <ComboboxValue placeholder="Select country..." />
8
  </ComboboxTrigger>
9
  <ComboboxContent>
10
    <ComboboxInput showTrigger={false} placeholder="Search countries..." />
11
    <ComboboxList>
12
      <ComboboxEmpty>No countries found.</ComboboxEmpty>
13
      <ComboboxItem value="brazil" label="Brazil">Brazil</ComboboxItem>
14
      <ComboboxItem value="canada" label="Canada">Canada</ComboboxItem>
15
      <ComboboxItem value="france" label="France">France</ComboboxItem>
16
      <ComboboxItem value="germany" label="Germany">Germany</ComboboxItem>
17
      <ComboboxItem value="japan" label="Japan">Japan</ComboboxItem>
18
    </ComboboxList>
19
  </ComboboxContent>
20
</Combobox>

API Reference

Events

The combobox emits custom events that you can listen to:

Event	Detail	Description
`combobox:change`	`{ value: string \| null }`	Fired when a new value is selected
`combobox:open-change`	`{ open: boolean }`	Fired when the dropdown opens or closes
`combobox:input-change`	`{ inputValue: string }`	Fired when the user types in the input

1
<Combobox id="my-combobox">
2
  <ComboboxInput placeholder="Search..." />
3
  <ComboboxContent>
4
    <ComboboxList>
5
      <ComboboxItem value="option1">Option 1</ComboboxItem>
6
      <ComboboxItem value="option2">Option 2</ComboboxItem>
7
    </ComboboxList>
8
  </ComboboxContent>
9
</Combobox>
10

11
<script>
12
  const combobox = document.getElementById('my-combobox');
13

14
  combobox.addEventListener('combobox:change', (e) => {
15
    console.log('Selected value:', e.detail.value);
16
  });
17

18
  combobox.addEventListener('combobox:input-change', (e) => {
19
    console.log('Input text:', e.detail.inputValue);
20
  });
21
</script>

Programmatic Control

You can control the combobox programmatically by dispatching a combobox:set event:

const combobox = document.getElementById('my-combobox');

// Set a specific value
combobox.dispatchEvent(new CustomEvent('combobox:set', {
  detail: { value: 'option2' }
}));

// Clear the value
combobox.dispatchEvent(new CustomEvent('combobox:set', {
  detail: { value: null }
}));

// Open the dropdown
combobox.dispatchEvent(new CustomEvent('combobox:set', {
  detail: { open: true }
}));

// Set the input text
combobox.dispatchEvent(new CustomEvent('combobox:set', {
  detail: { inputValue: 'search term' }
}));

// Custom display text for selected value
// itemToStringValue — (item: HTMLElement | null, value: string | null) => string
// Controls what text appears in the input after selection.
// Useful when items contain rich content (icons, descriptions).
combobox.dispatchEvent(new CustomEvent('combobox:set', {
  detail: {
    itemToStringValue: (item, value) => value ? `TZ: ${value}` : ''
  }
}));

Data Attributes

The combobox sets these data attributes that you can use for styling or querying state:

Attribute	Element	Description
`data-state`	combobox, combobox-content	Current state (`open` or `closed`)
`data-value`	combobox	Currently selected value
`data-selected`	combobox-item	Present when item is selected
`data-highlighted`	combobox-item	Present when item is focused/highlighted
`data-disabled`	combobox, combobox-item	Present when disabled
`data-empty`	combobox-content	Present when no items match the filter

Positioning

Placement options are configured on ComboboxContent:

1
<Combobox>
2
  <ComboboxInput />
3
  <ComboboxContent side="top" align="start" sideOffset={8}>
4
    ...
5
  </ComboboxContent>
6
</Combobox>