Visão geral

O Combobox é um componente customizado construído sobre Command + Popover. Ideal para listas longas que precisam de busca.

Demo básica

Selecionado: nenhum

Import

import { Combobox } from "@/components/combobox"

Quando usar

Use Combobox quando a lista tiver mais de 5-7 opções e o usuário precisar filtrar. Para listas curtas, use Select. Para pesquisa livre sem seleção de opção fixa, use Command diretamente.

Variações

O Combobox aceita qualquer lista de opções com value e label.

Com valor pré-selecionado

Padrão de implementação

Como usar o Combobox em diferentes contextos do projeto.

Combobox básico

"use client"
import { useState } from "react"
import { Combobox } from "@/components/combobox"

const opcoes = [
  { value: "op1", label: "Opção 1" },
  { value: "op2", label: "Opção 2" },
  { value: "op3", label: "Opção 3" },
]

export function MeuCombobox() {
  const [valor, setValor] = useState("")

  return (
    <Combobox
      options={opcoes}
      value={valor}
      onValueChange={setValor}
      placeholder="Selecionar opção..."
    />
  )
}

Com largura customizada

<Combobox
  options={paises}
  value={pais}
  onValueChange={setPais}
  placeholder="País..."
  searchPlaceholder="Buscar país..."
  className="w-[300px]"
/>

Interface ComboboxOption

interface ComboboxOption {
  value: string  // identificador único
  label: string  // texto exibido na lista e no trigger
}

Props e uso

API do componente Combobox customizado.

Props

options

ComboboxOption[]

Lista de opções com value e label.

value

string

Valor atualmente selecionado.

onValueChange

(value: string) => void

Callback chamado ao selecionar uma opção. Passa string vazia quando deselecionado.

placeholder

string

Texto exibido no trigger quando nada está selecionado.

searchPlaceholder

string

Placeholder do campo de busca interno.

emptyMessage

string

Mensagem exibida quando nenhum resultado é encontrado.

disabled

boolean

Desabilita o combobox.

className

string

Classes adicionais para o botão trigger. Use para controlar a largura.

Acessibilidade

O trigger tem role="combobox" e aria-expanded gerenciados automaticamente.

A lista usa cmdk que herda comportamento de listbox com navegação por teclado (setas, Enter, Escape).

Para campos de formulário, associe com um label externo ou use dentro do componente Field/Form.

MN Design System · Primary #5FC318 · Brand Green #AFF000 · Font: Inter