Primitiveselection

Combobox

Stable

Campo em que a pessoa digita até a lista, com grupos, limpeza e seleção múltipla em chips. Composto sobre Base UI Combobox e sobre o InputGroup e o Button do Up Web DS. O Select mostra uma lista; o combobox deixa digitar dentro dela — o que só compensa depois do ponto em que varrer com os olhos para de funcionar, e cobra um preço real: o campo passa a aceitar texto que não casa com nada, então o estado vazio faz parte do contrato.

Instalação

npx up-web-ds add combobox

Gera check, chevron-down, close para a biblioteca de ícones do projeto (components.json → iconLibrary).

Preview

Basic

Default

Grouped

With Clear

Multiple

dialog

popover

All states

Basic

Default

Grouped

With Clear

Multiple

dialog

popover

Usage

@/components/ui/combobox

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from '@/components/ui/combobox'

Combobox

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17<Combobox>
  <ComboboxInput
    aria-label="Buscar um primitive"
    className="w-full max-w-xs"
    placeholder="Buscar um primitive"
  />

  <ComboboxContent>
    <ComboboxEmpty>Nenhum item com esse nome.</ComboboxEmpty>

    <ComboboxList>
      <ComboboxItem value="button">button</ComboboxItem>
      <ComboboxItem value="dialog">dialog</ComboboxItem>
      <ComboboxItem value="select">select</ComboboxItem>
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Props

Combobox

Props de Combobox
Prop	Type	Default	Description
actionsRef	`React.RefObject<AriaCombobox.Actions \| null>`	sem valor padrão	A ref to imperative actions. - `unmount`: Manually unmounts the combobox. Call this after any externally controlled closing animation finishes.
autoComplete	`string`	sem valor padrão	Provides a hint to the browser for autofill.
autoHighlight	`boolean`	`false`	Whether the first matching item is highlighted automatically while filtering.
children	`React.ReactNode`	sem valor padrão
defaultInputValue	`string \| number \| readonly string[]`	sem valor padrão	The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead.
defaultOpen	`boolean`	`false`	Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.
defaultValue	`ComboboxValueType<Value, Multiple> \| null`	sem valor padrão	The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
filter	`((itemValue: Value, query: string, itemToString?: ((itemValue: Value) => string) \| undefined) => boolean) \| null`	sem valor padrão	Filter function used to match items vs input query.
filteredItems	`readonly any[] \| readonly Group<any>[]`	sem valor padrão	Filtered items to display in the list. When provided, the list will use these items instead of filtering the `items` prop internally. Use when you want to control filtering logic externally with the `useFilter()` hook.
form	`string`	sem valor padrão	Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.
grid	`boolean`	`false`	Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
highlightItemOnHover	`boolean`	`true`	Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
id	`string`	sem valor padrão	The id of the component.
inline	`boolean`	`false`	Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root` composition, bind the Combobox's `open` and `onOpenChange` props to the `Dialog`'s `open` and `onOpenChange` state instead so the component resets its transient state (filter query, highlighted item, and input value) when the dialog closes.
inputRef	`React.Ref<HTMLInputElement>`	sem valor padrão	A ref to the hidden input element.
inputValue	`string \| number \| readonly string[]`	sem valor padrão	The input value of the combobox. Use when controlled.
isItemEqualToValue	`((itemValue: Value, value: Value) => boolean)`	sem valor padrão	Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison.
items	`readonly any[] \| readonly Group<any>[]`	sem valor padrão	The items to be displayed in the list. Can be either a flat array of items or an array of groups with items.
itemToStringLabel	`((itemValue: Value) => string)`	sem valor padrão	When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
itemToStringValue	`((itemValue: Value) => string)`	sem valor padrão	When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
limit	`number`	`-1`	The maximum number of items to display in the list.
locale	`Intl.LocalesArgument`	sem valor padrão	The locale to use for string comparison. Defaults to the user's runtime locale.
loopFocus	`boolean`	`true`	Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>.
modal	`boolean`	`false`	Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
multiple	`Multiple`	`false`	Whether multiple items can be selected.
name	`string`	sem valor padrão	Identifies the field when a form is submitted.
onInputValueChange	`((inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the input value changes.
onItemHighlighted	`((highlightedValue: Value \| undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void)`	sem valor padrão	Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. - `'none'`: the highlight changed programmatically.
onOpenChange	`((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the popup is opened or closed.
onOpenChangeComplete	`((open: boolean) => void)`	sem valor padrão	Event handler called after any animations complete when the popup is opened or closed.
onValueChange	`((value: ComboboxValueType<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: ComboboxRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the selected value of the combobox changes.
open	`boolean`	sem valor padrão	Whether the popup is currently open. Use when controlled.
openOnInputClick	`boolean`	`true`	Whether the popup opens when clicking the input.
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.
value	`ComboboxValueType<Value, Multiple> \| null`	sem valor padrão	The selected value of the combobox. Use when controlled.
virtualized	`boolean`	`false`	Whether the items are being externally virtualized.

Estende ComboboxRoot.Props<Value, Multiple>.

ComboboxValue

Props de ComboboxValue
Prop	Type	Default	Description
children	`React.ReactNode \| ((selectedValue: any) => React.ReactNode)`	sem valor padrão
placeholder	`React.ReactNode`	sem valor padrão	The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`.

Estende ComboboxPrimitive.Value.Props.

ComboboxTrigger

Props de ComboboxTrigger
Prop	Type	Default	Description
className	`string \| ((state: ComboboxTriggerState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
nativeButton	`boolean`	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxTriggerState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxTriggerState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (284 não listados).

ComboboxInput

Props de ComboboxInput
Prop	Type	Default	Description
showClear	`boolean`	`false`
showTrigger	`boolean`	`true`
className	`string \| ((state: ComboboxInputState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxInputState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxInputState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Input.Props. Aceita também os atributos padrão de um elemento React (304 não listados).

ComboboxContent

Props de ComboboxContent
Prop	Type	Default	Description
align	`Align`	`'start'`	How to align the popup relative to the specified side.
alignOffset	`number \| OffsetFunction`	`0`	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset 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.
anchor	`Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`	sem valor padrão	An element to position the popup against. By default, the popup will be positioned against the trigger.
className	`string \| ((state: ComboboxPopupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)`	sem valor padrão	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.
initialFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)`	sem valor padrão	Determines the element to focus when the popup is opened. - `false`: Do not move focus. - `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.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxPopupState>`	sem valor padrão	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.
side	`Side`	`'bottom'`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset	`number \| OffsetFunction`	`6`	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.
style	`React.CSSProperties \| ((state: ComboboxPopupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Popup.Props & Pick< ComboboxPrimitive.Positioner.Props, 'side' | 'align' | 'sideOffset' | 'alignOffset' | 'anchor' >. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxList

Props de ComboboxList
Prop	Type	Default	Description
children	`React.ReactNode \| ((item: any, index: number) => React.ReactNode)`	sem valor padrão
className	`string \| ((state: ComboboxListState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxListState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxListState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.List.Props. Aceita também os atributos padrão de um elemento React (274 não listados).

ComboboxItem

Props de ComboboxItem
Prop	Type	Default	Description
children	`React.ReactNode`	sem valor padrão
className	`string \| ((state: ComboboxItemState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
index	`number`	sem valor padrão	The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	sem valor padrão	An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxItemState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxItemState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.
value	`any`	`null`	A unique value that identifies this item.

Estende ComboboxPrimitive.Item.Props. Aceita também os atributos padrão de um elemento React (272 não listados).

ComboboxGroup

Props de ComboboxGroup
Prop	Type	Default	Description
className	`string \| ((state: ComboboxGroupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
items	`readonly any[]`	sem valor padrão	Items to be rendered within this group. When provided, child `Collection` components will use these items.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxGroupState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxGroupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Group.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxLabel

Props de ComboboxLabel
Prop	Type	Default	Description
className	`string \| ((state: ComboboxGroupLabelState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxGroupLabelState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxGroupLabelState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.GroupLabel.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxCollection

Props de ComboboxCollection
Prop	Type	Default	Description
children, obrigatória	`(item: any, index: number) => React.ReactNode`	sem valor padrão

Estende ComboboxPrimitive.Collection.Props.

ComboboxEmpty

Props de ComboboxEmpty
Prop	Type	Default	Description
className	`string \| ((state: ComboboxEmptyState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxEmptyState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxEmptyState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Empty.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxSeparator

Props de ComboboxSeparator
Prop	Type	Default	Description
className	`string \| ((state: ComboboxSeparatorState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
orientation	`Orientation`	`'horizontal'`	The orientation of the separator.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxSeparatorState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxSeparatorState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Separator.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxChips

Props de ComboboxChips
Prop	Type	Default	Description
className	`string \| ((state: ComboboxChipsState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxChipsState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxChipsState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips> & ComboboxPrimitive.Chips.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxChip

Props de ComboboxChip
Prop	Type	Default	Description
showRemove	`boolean`	`true`
className	`string \| ((state: ComboboxChipState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxChipState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxChipState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Chip.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

ComboboxChipsInput

Props de ComboboxChipsInput
Prop	Type	Default	Description
className	`string \| ((state: ComboboxInputState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxInputState>`	sem valor padrão	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.
style	`React.CSSProperties \| ((state: ComboboxInputState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende ComboboxPrimitive.Input.Props. Aceita também os atributos padrão de um elemento React (304 não listados).

prop obrigatória.

Metadata

Notas de acessibilidade

Teclado verificado por teste: ArrowDown abre já com a primeira opção destacada, digitar estreita a lista em vez de exigir rolagem, Enter escolhe a opção destacada e Escape fecha sem tirar o foco do campo. Leitor de tela verificado por teste: o controle tem papel combobox, aria-expanded acompanha o estado, aria-controls aponta para o listbox portalizado, a opção escolhida é marcada por aria-selected, e quando nada casa o estado vazio é anunciado — um campo que aceita texto livre pode receber texto que não casa com nada, e não dizer nada de volta lê como campo quebrado. Em seleção múltipla cada chip é removível sozinho, verificado por teste: corrigir uma escolha entre duas não pode custar a outra. Touch verificado em navegador com emulação de toque em viewport de 375px: campo, opções e o botão de remover chip medem acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8, e o popup cabe na viewport. Reduced motion verificado com prefers-reduced-motion: reduce — os tokens de motion colapsam para 1ms e a animação de entrada do popup mede 0.001s.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: selection
Status: Stable

Origem e distribuição

Fonte: shadcn registry / combobox
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/combobox.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: check, chevron-down, close
Construído sobre: Input Group Button
Usado por: Nenhum ainda