---
title: "Combobox"
description: "Combobox with accessible presentation and local state."
---

# Combobox

Combobox with accessible presentation and local state.

## Installation

Install the shared package once in your Exact app. This version is a beta.

```sh
bun add --exact @rightui/ui@0.4.0-beta.4
```

Or choose another package manager:

```sh
npm install --save-exact @rightui/ui@0.4.0-beta.4
pnpm add --save-exact @rightui/ui@0.4.0-beta.4
yarn add --exact @rightui/ui@0.4.0-beta.4
```

Exact compilation uses Bun 1.4.2. Register Geist and Newsreader, declare the font marker and add the root provider using [Installation](/docs/installation).

### Manual source setup

Install an editable copy of the complete package:

```sh
mkdir -p vendor/rightui vendor/rightui-ui
npm pack @rightui/ui@0.4.0-beta.4 --pack-destination vendor/rightui
tar -xzf ./vendor/rightui/rightui-ui-0.4.0-beta.4.tgz -C vendor/rightui-ui --strip-components=1
bun add file:./vendor/rightui-ui
```

Keep package.json, the Contract files, ui.tamber, assets and licenses together.

### Import

```contract
use Combobox from "@rightui/ui"
```

## Usage

Import Combobox from @rightui/ui. Store its value in state and update it through the provided action callback.

## Example

```contract
use FontWeights from "@rightui/ui"
use uiFontFamily, Combobox from "@rightui/ui"

component Demo
  props
    width: number
    reduced: bool
  inject
    uiWeights: FontWeights
    uiFont: string
  derive narrow = width < 600
  state platform = "macOS"
  action setPlatform(v: string)
    platform = v
  view
    column gap="ui.space-16" min-width=0 max-width="100%"
      Combobox(id="catalog-platform", label="Platform", options=["iOS", "Android", "Web", "macOS", "Windows", "Linux"], value=platform, disabled=false, reduced=reduced, change=setPlatform)
      text "Disabled" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      Combobox(id="combobox-disabled", label="Unavailable platform", options=["Web"], value="Web", disabled=true, reduced=reduced, change=setPlatform)

```

## API Reference

| Property | Type |
| --- | --- |
| Combobox.id | string |
| Combobox.label | string |
| Combobox.options | string[] |
| Combobox.value | string |
| Combobox.disabled | bool |
| Combobox.reduced | bool |
| Combobox.change | action |

## Source

File: packages/ui/combobox.contract

```contract
use FontWeights from "./typography-context.contract"
use uiFontFamily from "./typography-context.contract"
use uiPopupIn, uiPopupOut from "./popup-motion.contract"
use Field, Control from "./styles.contract"
component Combobox
  props
    id: string
    label: string
    options: string[]
    value: string
    disabled: bool
    reduced: bool
    change: action
  inject
    uiWeights: FontWeights
    uiFont: string
  state expanded = false
  state openEpoch = 0
  state query = ""
  state width = 280
  derive filtered = options.filter(option => option.toLowerCase().includes(query.trim().toLowerCase()))
  action open
    if not disabled
      if expanded
        closeList()
      else
        let rect = frame(id)
        width = rect.width
        query = ""
        openEpoch = openEpoch + 1
        expanded = true
        showPopover(id + "-list", source=id)
        focus(id + "-search")
  action changed(epoch: number, e: ToggleEvent)
    if epoch == openEpoch
      expanded = e.newState == "open"

  action edit(v: string)
    query = v
  action closeList
    expanded = false
    focus(id)
  action pick(v: string)
    if not disabled
      change(v)
      closeList()
  action searchKeys(k: string, e: KeyboardEvent)
    if not e.isComposing
      if k == "Escape"
        preventDefault()
        closeList()
      else if k == "ArrowDown" and filtered.length > 0
        preventDefault()
        focus(id + "-option-0")
      else if k == "Enter" and filtered.length > 0
        preventDefault()
        match first(filtered)
          case some(v)
            pick(v)
          case none
            preventDefault()
  action optionKeys(i: number, k: string)
    if k == "Enter" or k == " "
      preventDefault()
      match filtered.at(i)
        case some(v)
          pick(v)
        case none
          closeList()
    else if k == "Escape"
      preventDefault()
      closeList()
    else if k == "ArrowUp" or k == "ArrowDown" or k == "Home" or k == "End"
      preventDefault()
      let next = (k == "Home" ? 0 : k == "End" ? filtered.length - 1 : min(filtered.length - 1, i + (k == "ArrowDown" ? 1 : -1)))
      focus(next < 0 ? id + "-search" : id + "-option-" + next.toString())
  view
    column gap="ui.space-8" min-width="0px"
      text label id=(id + "-label") font-size="ui.text-sm" font-weight=uiWeights.medium color="ui.foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      button id=id testId=id class=Field font-weight=uiWeights.regular disabled=disabled press=open aria-expanded=expanded aria-controls=(id + "-list") aria-haspopup="listbox" aria-labelledby=(id + "-label")
        display="flex" align-items="center" justify-content="space-between" gap="ui.space-8"
        text (value == "" ? "Choose…" : value) flex=1 min-width="0px" text-align="left" font-family=uiFontFamily(uiFont) data-rightui-font="body"
        svg width="ui.space-16" height="ui.space-16" viewBox="0 0 24 24" fill="none" stroke="ui.muted-foreground" stroke-width="ui.stroke-medium" aria-hidden=true
          path d="m8 9 4-4 4 4m-8 6 4 4 4-4"
      if expanded
        for epoch in [openEpoch] key=epoch
          column id=(id + "-list") testId=(id + "-list") popover="auto" toggle=changed(epoch)
            position-area="bottom" position-try-fallbacks="flip-block, flip-inline, flip-block flip-inline"
            animation=(reduced ? "none" : "uiPopupIn ui.duration-fast ui.easing both")
            -exact-exit-animation=(reduced ? "none" : "uiPopupOut ui.duration-fast ui.easing both")
            width=width max-width="calc(100vw - ui.space-32)" max-height="min(30rem, 70vh)" box-sizing="border-box" margin="ui.space-4" padding="0px" gap="0px"
            border-width="ui.border-width" border-style="solid" border-color="ui.border" border-radius="ui.radius-menu" background-color="ui.surface" box-shadow="ui.shadow-menu"
            input id=(id + "-search") testId=(id + "-search") class=Field font-weight=uiWeights.regular value=query input=edit key=searchKeys font-family=uiFontFamily(uiFont) data-rightui-font="body"
              role="combobox" aria-expanded=true aria-controls=(id + "-options") aria-description="Type to filter, then use Arrow Down to browse results." aria-label=("Rechercher : " + label) placeholder="Rechercher…" border="none" border-bottom-width="ui.border-width" border-bottom-style="solid" border-bottom-color="ui.border" border-radius="0px" min-height="ui.space-40" padding="ui.space-8 ui.space-12"
            scroll min-height="0px" flex="1 1 auto" max-height="18rem"
              column id=(id + "-options") role="listbox" aria-label=label gap="0px" padding="ui.space-4"
                for option, i in filtered key=option
                  button id=(id + "-option-" + i.toString()) testId=(id + "-option-" + i.toString()) class=Control role="option" aria-selected=(value == option)
                    press=pick(option) key=optionKeys(i) tabindex=-1 min-height="ui.space-32" padding="ui.space-6 ui.space-8" border="0" border-radius="ui.radius-item" font-weight=uiWeights.regular background-color=(value == option ? "ui.muted" : "ui.surface") color="ui.foreground"
                    text option text-align="left" font-size="ui.text-sm" font-family=uiFontFamily(uiFont) data-rightui-font="body"
                if filtered.length == 0
                  text "No results." testId=(id + "-empty") role="status" padding="ui.space-12" font-size="ui.text-caption" color="ui.muted-foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"

```
