Command

El componente Command implementa un patrón de “command palette” (similar a VS Code Cmd+K o Spotlight en macOS) que permite a los usuarios buscar y seleccionar opciones mediante un popover con búsqueda. Es ideal para listas largas donde la búsqueda rápida es esencial.

Diferencia con Combobox

Característica	Command	Combobox
Interfaz	Botón que abre popover	Input con dropdown
Búsqueda	✅ En popover	✅ En input
Renderizado	Button + Popover + Command	Input + Popover + Combobox
Uso recomendado	Acciones/comandos	Selección de datos
Estilo	Más prominente (botón)	Más discreto (input)

Properties

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

Basic Properties

Property	Type	Required	Default	Description
type	"command"	Yes	-	Especifica el tipo como command
options	Array<{ label: string; value: string; icon?: ReactNode }>	Yes	-	Lista de opciones disponibles. Puede incluir iconos
placeholder	string	No	-	Texto del botón 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 Command

Un command palette básico con iconos

basic-command.tsx

import { createExampleForm } from "../createExampleForm";
import { Mail, MapPin, Phone, User } from "lucide-react";
import { z } from "zod";

export const BasicCommand = createExampleForm({
  formId: "basic-command",
  fields: {
    contact: {
      type: "command",
      label: "Método de contacto",
      placeholder: "Selecciona un método de contacto",
      searchPlaceholder: "Buscar método...",
      emptyText: "No se encontraron métodos",
      options: [
        { label: "Email", value: "email", icon: <Mail className="w-4 h-4" /> },
        {
          label: "Teléfono",
          value: "phone",
          icon: <Phone className="w-4 h-4" />,
        },
        {
          label: "Dirección",
          value: "address",
          icon: <MapPin className="w-4 h-4" />,
        },
        { label: "Usuario", value: "user", icon: <User className="w-4 h-4" /> },
      ],
      schema: z.string().min(1, "Por favor selecciona un método de contacto"),
      helperText: "Busca y selecciona tu método de contacto preferido",
    },
  },
  steps: {
    step1: {
      id: "step1",
      fields: ["contact"],
    },
  },
});

Características

1. Command Palette Pattern: Implementa el patrón de paleta de comandos popularizado por herramientas como VS Code
2. Búsqueda instantánea: Los usuarios pueden escribir para filtrar opciones en tiempo real
3. Iconos visuales: Soporta iconos en cada opción para mejor identificación visual
4. Navegación por teclado: Soporte completo para navegación con teclado
5. Toggle de selección: Al seleccionar la opción ya seleccionada, se deselecciona

Casos de Uso

• Selección de acciones: Cuando el usuario necesita elegir entre múltiples acciones
• Navegación rápida: Para navegar entre secciones o páginas
• Búsqueda de entidades: Para buscar y seleccionar usuarios, productos, etc.
• Configuración: Para seleccionar opciones de configuración
• Filtros avanzados: Para aplicar filtros complejos con búsqueda

Best Practices

1. Usa iconos descriptivos: Los iconos ayudan a identificar rápidamente las opciones
2. Etiquetas claras: Asegúrate de que las etiquetas sean buscables y descriptivas
3. Ordena por relevancia: Coloca las opciones más usadas al principio
4. Personaliza mensajes: Ajusta searchPlaceholder y emptyText según el contexto
5. Implementa validación: Usa esquemas Zod para validar la selección

Interacción del Usuario

1. El usuario hace clic en el botón para abrir el popover
2. Aparece un campo de búsqueda en la parte superior
3. Al escribir, las opciones se filtran automáticamente
4. El usuario puede navegar con las flechas del teclado
5. Al presionar Enter o hacer clic, se selecciona la opción
6. El popover se cierra y el botón muestra la opción seleccionada

Accessibility

• El command 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
• El popover es accesible para usuarios de teclado y lectores de pantalla

Next Steps

• Combobox Component - Para comparar con el selector con búsqueda
• Select Component - Para el selector estándar
• Form Layout Guide
• Validation Guide