Combobox

Elegir de una lista larga con búsqueda (equipos, miembros). Flechas + Enter.

Extensión de la galería, sin uso actual en la app. Lista con búsqueda sobre Base UI. El input conserva el foco mientras la lista filtra opciones. El dashboard actual usa Select nativo o sus filtros propios.

Instalación

shadcn

npx shadcn@latest add https://design.moodinary.com/r/combobox.json

import

import { Combobox, ComboboxInput, ComboboxContent, ComboboxItem } from "@moodinary/ui/components/combobox";

Ejemplos

Buscar un equipo

Escribí parte del nombre para filtrar. Las flechas recorren los resultados; Enter elige y Escape cierra. Una búsqueda sin coincidencias muestra el estado vacío.

Equipo

Código

default.tsx

"use client";

import {
	Combobox,
	ComboboxContent,
	ComboboxInput,
	ComboboxItem,
} from "@moodinary/ui/components/combobox";
import { Field, FieldLabel } from "@moodinary/ui/components/field";

const TEAMS = [
	"1.º A",
	"1.º B",
	"2.º A",
	"2.º B",
	"3.º A",
	"3.º B",
	"4.º A",
	"4.º B",
	"5.º A",
	"5.º B",
	"6.º A",
	"Preceptoría",
	"Docentes nivel medio",
	"Equipo directivo",
	"Operaciones",
	"Atención al cliente",
	"Administración",
];

export default function ComboboxDefault() {
	return (
		<Field className="w-full max-w-[320px]">
			<FieldLabel htmlFor="team-combobox">Equipo</FieldLabel>
			<Combobox items={TEAMS}>
				<ComboboxInput id="team-combobox" placeholder="Buscar equipo…" />
				<ComboboxContent empty="Sin resultados para esa búsqueda">
					{(team: string) => (
						<ComboboxItem key={team} value={team}>
							{team}
						</ComboboxItem>
					)}
				</ComboboxContent>
			</Combobox>
		</Field>
	);
}

Props

Combobox

Prop	Tipo	Default	Descripción
items	readonly Value[] \| grouped items	-	Fuente de opciones para el filtrado de Base UI.
value / defaultValue	Value \| null	-	Selección controlada o inicial en modo de selección única.
onValueChange	(value: Value \| null, details: Combobox.Root.ChangeEventDetails) => void	-	Recibe la opción elegida.
itemToStringLabel	(item: Value) => string	-	Texto visible cuando las opciones son objetos.
disabled	boolean	false	Bloquea la búsqueda y la selección.

ComboboxInput

Prop	Tipo	Default	Descripción
id	string	-	Referencia del label visible.
placeholder	string	-	Indicación breve de búsqueda, no reemplaza el label.
...props	Combobox.Input.Props	-	Props del input de Base UI, incluidas las referencias de ayuda.

ComboboxContent

Prop	Tipo	Default	Descripción
children	Combobox.List.Props["children"]	-	Función que renderiza un ComboboxItem para cada opción.
empty	React.ReactNode	"Sin resultados"	Mensaje cuando el filtro no encuentra opciones.
sideOffset	number	6	Distancia en píxeles entre input y popup.

ComboboxItem

Prop	Tipo	Default	Descripción
value	unknown	-	Valor de la opción, consistente con items.
children	React.ReactNode	-	Texto visible de la opción.
disabled	boolean	false	Opción visible que no se puede elegir.

Cuándo sí y cuándo no

Hacé

Usá búsqueda cuando la lista es larga.
Mostrá un mensaje sin resultados.
Pasá itemToStringLabel si cada ítem es un objeto.

Evitá

No hagas que buscar cambie la selección antes de confirmar.
No uses el placeholder como único nombre.
No agregues roles manuales sobre los que ya maneja Base UI.

ArrowDown y ArrowUp recorren la lista; Enter confirma y Escape cierra.
El foco queda en el input y aria-activedescendant señala la opción activa.
Tab sale del componente; enlazá el label con el id del input.

Combobox

Instalación

Ejemplos

Buscar un equipo

Props

Combobox

ComboboxInput

ComboboxContent

ComboboxItem

Cuándo sí y cuándo no

Accesibilidad