Todos los componentes (204)

Lista seleccionable

Elección · SelectableList

Qué es y cuándo usarlo

Una lista de opciones a la vista, sin desplegar, para elegir una o marcar varias. Cada opción puede llevar una descripción, un icono y un detalle a la derecha (un importe, una fecha, un contador), y la lista puede ir por secciones.

Cuándo usarlo

Cuando las opciones tienen que estar delante para compararlas: la plantilla de una factura, una dirección guardada.
selection="multiple" para marcar varias filas de una lista corta y hacer algo con ellas.
maxHeight cuando la lista es larga: el scroll va dentro de la lista, no en la página.
loading mientras llegan las opciones: la lista se marca ocupada y sale una fila con loadingText («Cargando…»); las que ya hubiera se quedan.

Cuándo no

Una lista larga dentro de un formulario: Select, o SearchField si hay que buscar.
Repartir cosas entre dos columnas: TransferList, que ya usa esta lista por dentro.
Datos con columnas que se ordenan y se filtran: Table.

Teclado: Tab entra en la lista con el foco en la opción elegida (o en la primera). Las flechas se mueven saltándose las deshabilitadas, Inicio y Fin van a los extremos y escribir salta a la opción que empieza por esas letras -sin tildes vale: «e» encuentra «Éxito»-. Intro o Espacio eligen; con multiple, marcan y desmarcan sin soltar las demás, y con Mayúsculas marcan todo el tramo desde la última pulsada. Las deshabilitadas no se eligen.

Accesibilidad: es un listbox que se llama como la label, y cada opción es un option con su estado de elegida. La descripción se lee como descripción de la opción; el icono es decorativo. Sin opciones, dice el texto de empty en vez de dejar un hueco en blanco.

Estados: cada fila se oscurece al pasar el ratón y un poco más al pulsarla; la elegida va en el fondo suave de acento y el visto se dibuja al elegirla (y se borra, más deprisa, al soltarla). El foco de teclado es un anillo de 2 px por dentro de la fila, que la lista recorta al hacer scroll. Las deshabilitadas van en gris y con el cursor de prohibido. Las filas que aparecen (al montar, al filtrar) entran con un fundido corto.

Tamaños: sm, md (por defecto) y lg: filas de 30, 36 o 44 px de alto como mínimo, con la letra de los campos del mismo tamaño. Con el dedo ninguna fila baja de 44 px.

Aspecto fino: variables CSS en .amset-list-sel (la VirtualList usa las mismas, salvo el alto de fila, que allí es su rowHeight):

Medidas: --amset-list-sel-height-row, --amset-list-sel-padding (a los lados), --amset-list-sel-padding-block (arriba y abajo), --amset-list-sel-slot (entre filas), --amset-list-sel-radius (la caja) y --amset-list-sel-radius-row.
Letra e iconos: --amset-list-sel-font, --amset-list-sel-description (descripción, detalle y vacío), --amset-list-sel-icon y --amset-list-sel-brand (el visto).
Colores: --amset-list-sel-background, --amset-list-sel-border, --amset-list-sel-hover, --amset-list-sel-selected (fondo de la elegida), --amset-list-sel-ink-selected y --amset-list-sel-color-brand.

La marca de elegida ocupa sitio siempre, para que las filas no bailen al elegir.

Cómo se ve

<SelectableList
  label="Plantilla de la factura"
  options={[
    { key: 'basica', label: 'Factura basica', description: 'Sin logotipo', detail: '12 usos' },
    { key: 'completa', label: 'Factura completa', description: 'Con logotipo y pie legal' },
  ]}
  initialValue="completa"
/>
<SelectableList label="Pedidos para imprimir" selection="multiple" options={pedidos} maxHeight="14rem" />

Props

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

Prop	Tipo	Para qué sirve
`label`obligatoria	`string`	Que lista es esta. Obligatorio: sin nombre es "lista" a secas.
`options`obligatoria	`readonly ListOption[] \| readonly ListSection[]`	Las opciones sueltas, o todas por secciones (con su titulo).
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`empty`	`ReactNode`	Texto cuando no hay nada. Un hueco en blanco parece que se ha roto.
`initialValue`	`string \| readonly string[]`	—
`loading`	`boolean`	Las opciones estan llegando. La lista se marca ocupada y se enseña una fila `loadingText`; las que ya hubiera se quedan (buscar mas, refrescar).
`loadingText`	`string`	Lo que dice la fila de carga. Por defecto, «Cargando…».
`maxHeight`	`string`	Alto maximo antes de hacer scroll dentro de la lista.
`onChange`	`((key: string \| null) => void) \| ((keys: readonly string[]) => void)`	—
`renderOption`	`OptionRender<ListOption>`	Pinta el interior de cada opcion: un avatar, dos lineas, un precio. Lo que LEE el lector de pantalla sigue siendo `label` (y `description`); esto es solo lo que se ve.
`selection`	`"multiple" \| "single"`	—
`size`	`"sm" \| "md" \| "lg"`	Alto de fila y cuerpo de letra: `sm` (30 px), `md` (36 px, por defecto) o `lg` (44 px). Con el dedo ninguna fila baja de 44 px.
`value`	`string \| readonly string[] \| null`	—

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: