Todos los componentes (204)

Buscador

Campos · SearchField

Qué es y cuándo usarlo

El campo con autocompletado: se escribe y la lista se va filtrando, sin distinguir tildes ni mayúsculas. Cada vez que cambia el texto se anuncia cuántas opciones quedan («3 opciones»), que es lo que lo hace usable sin ver la pantalla.

Cuándo usarlo

Elegir de una lista larga: clientes, productos, proveedores.
serverFiltered cuando la búsqueda la hace el servidor: se le pasa la lista ya filtrada y se escucha onInputChange; loading mientras llega.
allowsCustomValue para quedarse con algo que no está en la lista (un proveedor nuevo).
Cada opción puede llevar una segunda línea (description), un icon y estar deshabilitada (disabled).

Cuándo no

Una lista corta y cerrada: Select. Un desplegable de cuatro opciones no necesita buscador.
Elegir varias: MultiSelect.
Buscar acciones o pantallas de la aplicación: CommandPalette.

Teclado: el foco se queda siempre en el campo, para poder seguir escribiendo. Flecha abajo abre la lista desde la primera opción y flecha arriba desde la última; las flechas la recorren, Intro elige y Tab cierra la lista y sale. Escape cierra la lista y devuelve el texto a lo que estaba elegido; dejar el campo en blanco y salir quita la elección. El botón de la flecha abre la lista entera con el ratón o el dedo; no está en el orden del Tab.

Accesibilidad: es un combobox y la opción activa se anuncia desde el campo con aria-activedescendant. La etiqueta es obligatoria; la ayuda y el error se leen como descripción. Si lo escrito no encuentra nada, la lista no se cierra de golpe: dice «Sin resultados» (noResultsMessage). Las opciones deshabilitadas se anuncian como tales y no se pueden elegir.

Aspecto fino: sin variables propias: la caja usa las del campo (--amset-field-*) y se ajusta con las clases amset-search__group, amset-search__open y amset-search__panel; la lista es la de siempre (amset-listbox, amset-option).

Cómo se ve

Cliente

Prueba con «alv» o «joyeria»: sin tilde también vale.

<SearchField
  label="Cliente"
  placeholder="Escribe el nombre del cliente"
  noResultsMessage="Ningun cliente con ese nombre"
  options={[
    { key: 'aurelia', label: 'Joyeria Aurelia', description: 'Madrid · 32 pedidos' },
    { key: 'bravo', label: 'Bravo Plateria', description: 'Cordoba · 9 pedidos' },
  ]}
  onSelectionChange={setCliente}
/>

Props

Se importa con import { SearchField } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`label`obligatoria	`string`	—
`options`obligatoria	`readonly ListOption[]`	—
`allowsCustomValue`	`boolean`	Deja confirmar un texto que no esta en la lista. Sin esto, al salir del campo el texto vuelve a la opcion elegida: un buscador de una lista cerrada no puede quedarse con algo que no existe.
`autoFocus`	`boolean`	—
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`defaultInputValue`	`string`	—
`defaultSelectedKey`	`string \| null`	La clave elegida al empezar, sin controlarla desde fuera.
`disabled`	`boolean`	—
`error`	`string`	—
`hiddenLabel`	`boolean`	La etiqueta solo para el lector de pantalla. Para cuando el campo va dentro de algo que ya se explica solo (una celda de tabla, un grupo de filtros), nunca para ahorrar espacio.
`hint`	`string`	—
`inputValue`	`string`	El texto escrito, controlado desde fuera.
`invalid`	`boolean`	—
`loading`	`boolean`	Las opciones estan llegando. Marca el campo como ocupado, enseña un anillo y una fila `loadingText` en la lista; las opciones que ya hubiera se quedan.
`loadingText`	`string`	Lo que dice la fila de carga. Por defecto, «Cargando…».
`menuTrigger`	`"input" \| "focus" \| "manual"`	Que abre la lista: `input` (por defecto) al escribir, `focus` en cuanto el campo recibe el foco, y `manual` solo con el boton o con las flechas.
`name`	`string`	Para que la clave elegida viaje en un formulario nativo.
`noResultsMessage`	`string`	Texto cuando lo que se escribe no encuentra nada.
`offset`	`number`	Separacion en pixeles entre el campo y la lista. Por defecto, ninguna.
`onBlur`	`() => void`	Al salir del campo. Lo usa el formulario para marcar que se ha tocado.
`onInputChange`	`(text: string) => void`	—
`onOpenChange`	`(open: boolean) => void`	Al abrirse o cerrarse la lista.
`onSelectionChange`	`(key: string \| null) => void`	—
`placeholder`	`string`	—
`placement`	`Placement`	Donde sale la lista. Por defecto, pegada justo debajo del campo.
`readOnly`	`boolean`	—
`renderOption`	`OptionRender<ListOption>`	Pinta el interior de cada opcion de la lista: un avatar, dos lineas, un precio. El nombre que lee el lector de pantalla sigue siendo `label`.
`required`	`boolean`	—
`selectedKey`	`string \| null`	La clave elegida, controlada desde fuera.
`serverFiltered`	`boolean`	La lista ya viene filtrada de fuera (busqueda en el servidor). Por defecto filtra el propio componente con lo que se escribe.
`size`	`"sm" \| "md" \| "lg"`	—
`validationBehavior`	`"aria" \| "native"`	—
`variant`	`FieldVariant`	—

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: