Radix Vue

Appearance

Combobox ​

Choose from a list of suggested values with full keyboard support.

Features ​

  • Can be controlled or uncontrolled.
  • Offers 2 positioning modes.
  • Supports items, labels, groups of items.
  • Focus is fully managed.
  • Full keyboard navigation.
  • Supports custom placeholder.
  • Supports Right to Left direction.

Installation ​

Install the component from your command line.

bash
npm install radix-vue

Anatomy ​

Import all parts and piece them together.

vue
<script setup lang="ts">
import {
  ComboboxAnchor,
  ComboboxArrow,
  ComboboxCancel,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxItemIndicator,
  ComboboxLabel,
  ComboboxPortal,
  ComboboxRoot,
  ComboboxSeparator,
  ComboboxTrigger,
  ComboboxViewport,
} from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxAnchor>
      <ComboboxInput />
      <ComboboxTrigger />
      <ComboboxCancel />
    </ComboboxAnchor>

    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxViewport>
          <ComboboxEmpty />

          <ComboboxItem>
            <ComboboxItemIndicator />
          </ComboboxItem>

          <ComboboxGroup>
            <ComboboxLabel />
            <ComboboxItem>
              <ComboboxItemIndicator />
            </ComboboxItem>
          </ComboboxGroup>
          <ComboboxSeparator />
        </ComboboxViewport>

        <ComboboxArrow />
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

API Reference ​

Root ​

Contains all the parts of a Combobox

PropTypeDefault
defaultValue
string | string[] | object | object[]
modelValue
string | string[] | object | object[]
defaultOpen
boolean
open
boolean
searchTerm
string
filterFunction
(val: Array<string | any>, term: string) => Array<any>
multiple
boolean
dir
enum
name
string
disabled
boolean
EmitType
@update:modelValue
(value: string) => void
@update:open
(open: boolean) => void
@update:searchTerm
(value: string) => void

The header section of Combobox. Used as an anchor if you set ComboboxContent's position to popper.

PropTypeDefault
asChild
boolean
false

Input ​

The input component to search through the combobox items.

Trigger ​

The button that toggles the Combobox Content.

PropTypeDefault
asChild
boolean
false
Data AttributeValue
[data-state]"open" | "closed"
[data-disabled]Present when disabled

Cancel ​

The button that clears the search term.

PropTypeDefault
asChild
boolean
false

Portal ​

When used, portals the content part into the body.

PropTypeDefault
to
string | HTMLElement
body

Content ​

The component that pops out when the combobox is open.

PropTypeDefault
position
enum
"inline"
bodyLock
boolean
false
disableOutsidePointerEvents
boolean
false
side
enum
"bottom"
sideOffset
number
0
align
enum
"start"
alignOffset
number
0
avoidCollisions
boolean
true
collisionBoundary
Boundary
[]
collisionPadding
number | Padding
10
arrowPadding
number
0
sticky
enum
"partial"
hideWhenDetached
boolean
false
asChild
boolean
false
EmitType
@closeAutoFocus
(event: Event) => void
@escapeKeyDown
(event: KeyboardEvent) => void
@pointerDownOutside
(event: PointerDownOutsideEvent) => void
Data AttributeValue
[data-state]"open" | "closed"
[data-side]"left" | "right" | "bottom" | "top"
[data-align]"start" | "end" | "center"
CSS VariableDescription
--radix-combobox-content-transform-origin
The transform-origin computed from the content and arrow positions/offsets. Only present when position="popper".
--radix-combobox-content-available-width
The remaining width between the trigger and the boundary edge. Only present when position="popper".
--radix-combobox-content-available-height
The remaining height between the trigger and the boundary edge. Only present when position="popper".
--radix-combobox-trigger-width
The width of the trigger. Only present when position="popper".
--radix-combobox-trigger-height
The height of the trigger. Only present when position="popper".

Viewport ​

The scrolling viewport that contains all of the items.

PropTypeDefault
asChild
boolean
false

Item ​

The component that contains the combobox items.

PropTypeDefault
value*
string
disabled
boolean
asChild
boolean
false
EmitType
@select
(event: SelectEvent) => void
Data AttributeValue
[data-state]"checked" | "unchecked"
[data-highlighted]Present when highlighted
[data-disabled]Present when disabled

ItemIndicator ​

Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

PropTypeDefault
asChild
boolean
false

Group ​

Used to group multiple items. use in conjunction with ComboboxLabel to ensure good accessibility via automatic labelling.

PropTypeDefault
asChild
boolean
false

Label ​

Used to render the label of a group. It won't be focusable using arrow keys.

PropTypeDefault
asChild
boolean
false

Separator ​

Used to visually separate items in the Combobox

PropTypeDefault
asChild
boolean
false

Arrow ​

An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the ComboboxContent. Must be rendered inside ComboboxContent. Only available when position is set to popper.

PropTypeDefault
asChild
boolean
false
width
number
10
height
number
5

Examples ​

Binding objects as values ​

Unlike native HTML form controls which only allow you to provide strings as values, radix-vue supports binding complex objects as well.

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxContent, ComboboxInput, ComboboxItem, ComboboxPortal, ComboboxRoot } from 'radix-vue'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]
const selectedPeople = ref(people[0])
</script>

<template>
  <ComboboxRoot v-model="selectedPeople">
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem
          v-for="person in people"
          :key="person.id"
          :value="person"
          :disabled="person.unavailable"
        >
          {{ person.name }}
        </ComboboxItem>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

Selecting multiple values ​

The Combobox component allows you to select multiple values. You can enable this by providing an array of values instead of a single value.

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxRoot } from 'radix-vue'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]
const selectedPeople = ref([people[0], people[1]])
</script>

<template>
  <ComboboxRoot v-model="selectedPeople" multiple>
    ...
  </ComboboxRoot>
</template>

Custom filtering ​

Internally, ComboboxRoot would apply default filter function to filter relevant ComboboxItem (only apply when modelValue is type string).

However this behavior can be replaced using 2 different method.

1. Provide filter-function props. ​

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxContent, ComboboxInput, ComboboxItem, ComboboxPortal, ComboboxRoot } from 'radix-vue'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]
const selectedPeople = ref(people[0])

function filterFunction(list: typeof people[number], searchTerm: string) {
  return list.filter((person) => {
    return person.name.toLowerCase().includes(searchTerm.toLowerCase())
  })
}
</script>

<template>
  <ComboboxRoot
    v-model="selectedPeople"
    :filter-function="filterFunction"
  >
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem
          v-for="person in people"
          :key="person.id"
          :value="person"
          :disabled="person.unavailable"
        >
          {{ person.name }}
        </ComboboxItem>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

2. Filtered v-for options ​

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxContent, ComboboxInput, ComboboxItem, ComboboxPortal, ComboboxRoot } from 'radix-vue'

const people = [
  { id: 1, name: 'Durward Reynolds' },
  { id: 2, name: 'Kenton Towne' },
  { id: 3, name: 'Therese Wunsch' },
  { id: 4, name: 'Benedict Kessler' },
  { id: 5, name: 'Katelyn Rohan' },
]
const selectedPeople = ref(people[0])
const searchTerm = ref('')

const filteredPeople = computed(() =>
  searchTerm.value === ''
    ? people
    : people.filter((person) => {
      return person.name.toLowerCase().includes(searchTerm.value.toLowerCase())
    })
)
</script>

<template>
  <ComboboxRoot
    v-model="selectedPeople"
    v-model:searchTerm="searchTerm"
  >
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem
          v-for="person in filteredPeople"
          :key="person.id"
          :value="person"
          :disabled="person.unavailable"
        >
          {{ person.name }}
        </ComboboxItem>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

Custom label ​

By default the Combobox will use the input contents as the label for screenreaders. If you'd like more control over what is announced to assistive technologies, use the Label component.

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxInput, ComboboxRoot, Label } from 'radix-vue'
</script>

<template>
  <ComboboxRoot v-model="selectedPeople">
    <Label for="person">Person: </Label>
    <ComboboxInput id="person" placeholder="Select a person" />
    ...
  </ComboboxRoot>
</template>

With disabled items ​

You can add special styles to disabled items via the data-disabled attribute.

vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ComboboxContent,
  ComboboxInput,
  ComboboxItem,
  ComboboxPortal,
  ComboboxRoot,
} from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem class="ComboboxItem" disabled>
          ...
        </ComboboxItem>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>
css
/* styles.css */
.ComboboxItem[data-disabled] {
  color: "gainsboro";
}

With separators ​

Use the Separator part to add a separator between items.

vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ComboboxContent,
  ComboboxInput,
  ComboboxItem,
  ComboboxPortal,
  ComboboxRoot,
  ComboboxSeparator
} from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem>…</ComboboxItem>
        <ComboboxItem>…</ComboboxItem>
        <ComboboxItem>…</ComboboxItem>
        <ComboboxSeparator />
        <ComboboxItem>…</ComboboxItem>
        <ComboboxItem>…</ComboboxItem>
        <ComboboxItem>…</ComboboxItem>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

With grouped items ​

Use the Group and Label parts to group items in a section.

vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ComboboxContent,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxPortal,
  ComboboxRoot
} from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxGroup>
          <ComboboxLabel>Label</ComboboxLabel>
          <ComboboxItem>…</ComboboxItem>
          <ComboboxItem>…</ComboboxItem>
          <ComboboxItem>…</ComboboxItem>
        </ComboboxGroup>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

With complex items ​

You can use custom content in your items.

vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ComboboxContent,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxItemIndicator,
  ComboboxLabel,
  ComboboxPortal,
  ComboboxRoot
} from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem>
          <img src="…">
          Adolfo Hess
          <ComboboxItemIndicator />
        </ComboboxItem>
        …
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

Prevent select behavior ​

By default, selecting ComboboxItem would close the content, and update the modelValue with the provided value. You can prevent this behavior by preventing default @select.prevent.

vue
<script setup lang="ts">
import { ref } from 'vue'
import { ComboboxContent, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxLabel, ComboboxPortal, ComboboxRoot } from 'radix-vue'
</script>

<template>
  <ComboboxRoot>
    <ComboboxInput />
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxItem @select.prevent>
          Item A
        </ComboboxItem>
        …
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>

Accessibility ​

Adheres to the Combobox WAI-ARIA design pattern.

See the W3C Combobox Autocomplete List example for more information.

Keyboard Interactions ​

KeyDescription
Enter
When focus is on ComboboxItem, selects the focused item.
ArrowDown
When focus is on ComboboxInput, opens the combobox content.
When focus is on an item, moves focus to the next item.
ArrowUp
When focus is on ComboboxInput, opens the combobox content.
When focus is on an item, moves focus to the previous item.
Esc
Closes combobox and restores the selected item in the ComboboxInput field.

Custom APIs ​

Create your own API by abstracting the primitive parts into your own component.

Command Menu ​

Combobox can be use to build your own Command Menu.

Usage ​

vue
<script setup lang="ts">
import { Command, CommandItem } from './your-command'
</script>

<template>
  <Command>
    <CommandItem value="1">
      Item 1
    </CommandItem>
    <CommandItem value="2">
      Item 2
    </CommandItem>
    <CommandItem value="3">
      Item 3
    </CommandItem>
  </Command>
</template>

Implementation ​

ts
// your-command.ts
export { default as Command } from 'Command.vue'
export { default as CommandItem } from 'CommandItem.vue'
vue
<!-- Command.vue -->
<script setup lang="ts">
import { CheckIcon, ChevronDownIcon, ChevronUpIcon, } from '@radix-icons/vue'
import { ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxPortal, ComboboxRoot, useForwardPropsEmits } from 'radix-vue'
import type { ComboboxRootEmits, ComboboxRootProps } from 'radix-vue'

const props = defineProps<ComboboxRootProps>()
const emits = defineEmits<ComboboxRootEmits>()

const forward = useForwardPropsEmits(props, emits)
</script>

<template>
  <ComboboxRoot v-bind="forward" :open="true" model-value="">
    <ComboboxInput placeholder="Type a command or search..." />

    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxEmpty />
        <ComboboxViewport>
          <slot />
        </ComboboxViewport>
      </ComboboxContent>
    </ComboboxPortal>
  </ComboboxRoot>
</template>
vue
<!-- ComboboxItem.vue -->
<script setup lang="ts">
import { CheckIcon } from '@radix-icons/vue'
import { ComboboxItem, type ComboboxItemProps } from 'radix-vue'

const props = defineProps<ComboboxItemProps>()
</script>

<template>
  <ComboboxItem v-bind="props" @select.prevent>
    <slot />
  </ComboboxItem>
</template>