'/%3e%3cg%20transform='translate(170%20205)%20scale(0.3606)'%20fill='%23111011'%3e%3cpath%20d='M497%20640H359L248%20320%20122%20640H0L256%200z'/%3e%3cpath%20d='M292.43%20640H200.8L248%20522z'/%3e%3cpath%20d='M335%200h138l111%20320L710%200h122L576%20640z'/%3e%3c/g%3e%3c/svg%3e){kind=small}
Formularios
ComboBox y TagField
Escribe para filtrar y elegir una opción, o varias como etiquetas que se pueden quitar.
import { ComboBox, TagField } from '@alea/ui';
Ejemplos
ComboBox
defaultItems filtra mientras escribes.
Texto libre
allowsCustomValue conserva lo que se escriba.
TagField
Varias opciones como etiquetas; Retroceso quita la última.
Borrar, prefijo y crear
isClearable vacía el texto y la selección; prefix agrega un ícono; footer ofrece crear lo escrito cuando nada coincide.
Búsqueda asíncrona
Filtra en el servidor: pasa tú los items, activa isLoading mientras corre la solicitud, y avisa cuando nada coincidió.
Configuraciones
Cada valor de cada propiedad, lado a lado. Los números coinciden con la leyenda.
- Size
size - Variant
variant
Estados
Cada estado de interacción, forzado para compararlos, en ambos temas.
Oscuro
Claro
Anatomía
Las partes del componente y la clase que da estilo a cada una.
Medidas
Medido del componente renderizado a 2x: alto, ancho, padding, radio e icono.
Cada tamaño y espacio es múltiplo de 4 px.
Tokens
Los tokens de diseño que usa este componente, con su valor en el tema actual. Cambia cualquiera para darle otro estilo.
Color
--alea-focus…--alea-focus-halo…--alea-text-muted…
Type
--alea-font-size-sm…
Props
ComboBox props
Escribe para filtrar una lista y elegir una opción. Pasa defaultItems para filtrar mientras se escribe, o items para filtrar tú (búsqueda asíncrona). allowsCustomValue conserva el texto libre.
| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
children | ReactNode | ((item: T) => ReactNode) | - | Cómo mostrar items personalizados; los items simples {id, label} se muestran como opciones. |
description | ReactNode | - | Texto de ayuda bajo el campo. |
emptyText | ReactNode | - | Se muestra cuando nada coincide. Por defecto "Sin coincidencias". |
errorMessage | ReactNode | ((v: ValidationResult) => ReactNode) | - | Texto de error, mostrado cuando es inválido. |
footer | ReactNode | - | Contenido debajo de la lista dentro del popover, como "Crear “…”". |
isClearable | boolean | - | Muestra un botón de borrar mientras hay texto o una selección. |
isLoading | boolean | - | Muestra un spinner, para resultados que están cargando (búsqueda asíncrona). |
label | ReactNode | - | La etiqueta visible. |
labelPosition | "top" | "side" | 'top' | top (por defecto) o side (desde 640 px). |
motion | MotionProp | - | Cómo entra y sale el popup: un preset (fade, scale, pop, slide-down, blur...), false para ninguno, u opciones. |
placeholder | string | - | Se muestra mientras el campo está vacío. |
prefix | ReactNode | - | Un ícono o texto antes del input. |
showOptional | boolean | - | Muestra "(opcional)" después de la etiqueta. |
size | Responsive<"xs" | "sm" | "md" | "lg" | "xl"> | - | xs 28 px, sm 32 px, md 44 px (por defecto), lg 48 px, xl 56 px. Puede cambiar por breakpoint. |
variant | "filled" | "outline" | "underline" | "borderless" | 'outline' | outline (por defecto), filled, underline o borderless, como TextField. |
virtualized | number | - | Muestra solo las opciones visibles: pasa la altura de fila (40). |
warningMessage | ReactNode | - | Una advertencia que no bloquea, mostrada bajo el campo en ámbar. |
TagField props
Elige varias opciones escribiendo; lo elegido se muestra como etiquetas que se pueden quitar.
| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
itemsobligatoria | SelectOption[] | - | Las opciones para elegir. |
allowsCustomValue | boolean | - | Permite agregar valores que no están en la lista (Enter). |
className | string | - | Clases extra para el elemento raíz. |
defaultValue | Key[] | - | Las etiquetas al inicio. |
description | ReactNode | - | Texto de ayuda mostrado bajo el campo. |
isDisabled | boolean | - | Deshabilita todas sus partes. |
label | ReactNode | - | La etiqueta visible. |
max | number | - | Máximo de opciones permitidas. |
onChange | ((value: Key[]) => void) | - | Se llama con las etiquetas. |
placeholder | string | - | Se muestra mientras no hay valor. |
style | CSSProperties | - | Estilos en línea para el elemento raíz. |
value | Key[] | - | Ids elegidos (controlado). |
Especificaciones
Generado desde el código: las variantes de los tipos, los estados y tokens del CSS, y los patrones de motion que aplican. Las grillas muestran el componente real en ambos temas; los números se miden en la página.
ComboBox
- Variantes
labelPositiontopsidevariantfilledoutlineunderlineborderless- Estados
- Focus inside
- Motion
- morphnudgeAcepta una prop motion para su entrada y salida.
- Oscuro y claro
- Cada color viene de tokens del tema, así que sigue a data-theme (y a presets como Graphite) en la página o en cualquier contenedor. El contraste se revisa en ambos temas.
- Clases para estilos
.alea-listbox-empty.alea-combobox.alea-label-required.alea-label-optional.alea-input-wrap.alea-input-affix.alea-input.alea-field-warning.alea-select-popover.alea-select-footer
TagField
- Motion
- press
- Oscuro y claro
- Cada color viene de tokens del tema, así que sigue a data-theme (y a presets como Graphite) en la página o en cualquier contenedor. El contraste se revisa en ambos temas.
- Clases para estilos
.alea-tagfield.alea-tagfield-tags.alea-tag.alea-tag-remove
Accesibilidad
- Un combobox con un listbox; la opción resaltada se anuncia mientras el foco sigue en el campo.
- Las etiquetas elegidas tienen botones para quitar con el nombre de la etiqueta.
Teclado
| Tecla | Acción |
|---|---|
| Escribir | Filtra |
| Flecha abajo / Arriba | Recorre las sugerencias |
| Enter | Elige (o agrega texto propio en TagField) |
| Escape | Cierra la lista |
| Retroceso (vacío) | Quita la última etiqueta |
Qué hacer y qué evitar
Hacer
- Usa defaultItems para filtrar mientras escriben, e items para filtrar por tu cuenta (búsqueda en el servidor).
Evitar
- No lo uses para menos de ocho opciones: usa Select.