Combobox

El componente Combobox es un selector con capacidad de búsqueda que permite a los usuarios filtrar y seleccionar una opción de una lista. Es ideal para listas largas donde la búsqueda mejora significativamente la experiencia de usuario.

Diferencia con Select

Característica	Select	Combobox
Búsqueda	❌ No	✅ Sí
Renderizado	Custom (Radix UI)	Custom (Radix UI + Command)
Uso recomendado	Listas cortas (< 10 opciones)	Listas largas o con muchas opciones
Interfaz	Dropdown estático	Popover con búsqueda

Properties

Además de las propiedades comunes, el componente combobox acepta las siguientes propiedades específicas:

Basic Properties

Property	Type	Required	Default	Description
type	"combobox"	Yes	-	Especifica el tipo como combobox
options	Array<{ label: string; value: string; icon?: ReactNode }>	Yes	-	Lista de opciones disponibles (puede incluir iconos)
placeholder	string	No	-	Texto placeholder del input cuando no hay selección
searchPlaceholder	string	No	"Search..."	Texto placeholder del campo de búsqueda dentro del popover
emptyText	string	No	"No option found."	Mensaje que se muestra cuando no hay resultados en la búsqueda
value	string	No	-	Valor inicial seleccionado

Examples

Basic Combobox

Un combobox básico con búsqueda

basic-combobox.tsx

import { createExampleForm } from "../createExampleForm";
import { z } from "zod";

export const BasicCombobox = createExampleForm({
  formId: "basic-combobox",
  fields: {
    country: {
      type: "combobox",
      label: "País",
      placeholder: "Buscar país...",
      searchPlaceholder: "Escribe para buscar...",
      emptyText: "No se encontraron países",
      options: [
        { label: "España", value: "es" },
        { label: "México", value: "mx" },
        { label: "Colombia", value: "co" },
        { label: "Argentina", value: "ar" },
        { label: "Chile", value: "cl" },
        { label: "Perú", value: "pe" },
        { label: "Venezuela", value: "ve" },
        { label: "Ecuador", value: "ec" },
      ],
      schema: z.string().min(1, "Por favor selecciona un país"),
      helperText: "Busca y selecciona tu país de residencia",
    },
  },
  steps: {
    step1: {
      id: "step1",
      fields: ["country"],
    },
  },
});

Características

1. Búsqueda en tiempo real: Los usuarios pueden escribir para filtrar las opciones
2. Navegación por teclado: Soporte completo para navegación con teclado (Arrow keys, Enter, Escape)
3. Accesible: Implementa correctamente ARIA attributes para lectores de pantalla
4. Iconos en opciones: Soporta iconos en cada opción para mejor UX visual
5. Mensajes personalizables: Puedes personalizar los placeholders y mensajes vacíos

Best Practices

1. Usa para listas largas: Ideal cuando tienes más de 10 opciones
2. Proporciona búsqueda útil: Asegúrate de que las etiquetas sean buscables (evita abreviaciones crípticas)
3. Considera el orden: Ordena las opciones de manera lógica para facilitar la búsqueda
4. Personaliza mensajes: Ajusta searchPlaceholder y emptyText según el contexto
5. Implementa validación: Usa esquemas Zod para validar la selección

Cuándo usar Combobox vs Select

• Usa Combobox cuando:

  • Tienes más de 10 opciones
  • Las opciones pueden ser difíciles de encontrar sin búsqueda
  • Quieres una mejor UX para listas largas
  • Necesitas búsqueda por texto

• Usa Select cuando:

  • Tienes menos de 10 opciones
  • Las opciones son bien conocidas
  • Prefieres un dropdown más simple
  • No necesitas búsqueda

Accessibility

• El combobox es automáticamente asociado con su etiqueta
• Los mensajes de error son anunciados correctamente a los lectores de pantalla
• El componente sigue las mejores prácticas de ARIA
• La navegación por teclado está completamente soportada
• La búsqueda es accesible para usuarios de teclado y lectores de pantalla

Next Steps

• Select Component - Para comparar con el selector estándar
• Native Select Component - Para el selector nativo del navegador
• Form Layout Guide
• Validation Guide