---
title: "Campo de cuadro combinado"
description: "Permite encontrar un valor escribiendo, como campo de un formulario: un cuadro combinado, con una lista de opciones que se reduce a medida que la persona escribe y de la que elige una o, donde el producto lo permite, un valor propio, bajo una etiqueta que puede decir si el campo es obligatorio u opcional, con una línea de ayuda y el motivo por el que se rechazó un valor."
url: "https://tanrei.chnotchy.com/es/components/combobox-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Campo de cuadro combinado

> Permite encontrar un valor escribiendo, como campo de un formulario: un cuadro combinado, con una lista de opciones que se reduce a medida que la persona escribe y de la que elige una o, donde el producto lo permite, un valor propio, bajo una etiqueta que puede decir si el campo es obligatorio u opcional, con una línea de ayuda y el motivo por el que se rechazó un valor.

## Descripción general

Usa un campo de cuadro combinado siempre que un formulario pida un valor que las personas prefieren escribir a buscar desplazándose: una ciudad entre cientos, una persona, un token. También sirve para un campo que sugiere valores y acepta uno propio de la persona, como una familia de fuentes. Es el caso corriente, listo para usarse: una etiqueta, la caja con su lista, una línea de ayuda y las palabras para un valor incorrecto. La caja se dibuja y se mide como la del campo de texto de la misma variante y el mismo tamaño, y la lista se dibuja como la de un select.

**Se compone de** un [campo](https://tanrei.chnotchy.com/es/components/field/) y un [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/). El campo es el marco: la etiqueta, la marca de obligatorio o de opcional, la ayuda y el error. El cuadro combinado es el control: la caja, el texto que se escribe en ella y la lista con sus opciones. El campo de cuadro combinado no dibuja nada propio y no tiene ningún token: cada propiedad que tiene es una propiedad de uno de los dos, que recibe sin cambios, y las opciones que le das son las de su cuadro combinado.

Es un bloque tan ancho como el lugar en el que se pone, y su caja lo llena. No tiene ancho propio: para un campo más estrecho, dale un lugar más estrecho. Su ancho nunca depende de sus opciones ni de su valor, porque la persona escribe en él antes de que se conozca ninguna opción.

En la web es `<tanrei-combobox-field>`, con elementos `<tanrei-option>` como hijos, los mismos que contiene un [select](https://tanrei.chnotchy.com/es/components/select/). Las demás plataformas todavía no lo han implementado.

### Uso

Un campo de cuadro combinado guarda lo que guarda su cuadro combinado, que son dos cosas. `value` es la elección confirmada: el valor de la opción elegida o un texto propio. `inputValue` es el texto del campo de entrada. El valor solo cambia cuando la persona elige una opción, confirma el texto (con Enter sin ninguna opción activa, o al salir del campo) o pulsa el botón de borrar; escribir y moverse por la lista nunca lo cambian.

**Web**

```html
<form>
  <tanrei-combobox-field name="city" label="Ciudad" value="tokyo" required required-text="Obligatorio"
    clearable clear-label="Borrar ciudad" empty-text="Sin coincidencias">
    <tanrei-option value="kyoto">Kioto</tanrei-option>
    <tanrei-option value="tokyo">Tokio</tanrei-option>
  </tanrei-combobox-field>
</form>

<!-- La caja sola, donde una etiqueta está en otro lugar: un cuadro combinado, que recibe su nombre de su propio label. Importar el campo de cuadro combinado lo define. -->
<tanrei-combobox label="Token" placeholder="Buscar un token" no-chevron style="inline-size: 16rem">
  <tanrei-option value="primary">primary</tanrei-option>
</tanrei-combobox>

<!-- Las opciones son sugerencias: un texto que no nombra ninguna pasa a ser el valor. -->
<tanrei-combobox-field label="Familia de fuentes" value="Recursive" allow-custom-value>
  <tanrei-option value="Inter">Inter</tanrei-option>
</tanrei-combobox-field>

<!-- Filtras tú: en cada evento input, desde un servidor. La fila de estado dice qué está haciendo tu fuente de datos. -->
<tanrei-combobox-field id="assignee" label="Persona asignada" filter="none" no-chevron placeholder="Buscar una persona">
  <span slot="leading-icon">person_search</span>
</tanrei-combobox-field>

<script type="module">
  import '@tanrei/web/components/combobox-field';

  const assignee = document.querySelector('#assignee');
  // La persona cambió el texto. El cuadro combinado no retrasa ni descarta este evento: aplica tú el debounce.
  assignee.addEventListener('input', async () => {
    assignee.status = 'loading';
    assignee.statusText = 'Cargando personas';
    const people = await find(assignee.inputValue);
    assignee.replaceChildren(...people.map(option));
    assignee.status = 'idle';
    assignee.statusText = `Se muestran ${people.length} de ${total} personas`;
  });
  // El valor confirmado cambió. El valor ya es el nuevo.
  assignee.addEventListener('change', (e) => save(e.detail.value));
  // La persona abrió o cerró la lista; un cierre dice por qué. No se propaga: escúchalo en el propio campo.
  assignee.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
</script>
```

**React**

```tsx
import { ComboboxField, Option } from '@tanrei/react';

<ComboboxField label="Ciudad" value={city} clearable clearLabel="Borrar ciudad" emptyText="Sin coincidencias" onChange={(event) => setCity(event.detail.value)}>
  <Option value="kyoto">Kioto</Option>
  <Option value="tokyo">Tokio</Option>
</ComboboxField>
```

### Un nivel más abajo

Un campo de cuadro combinado es un [campo](https://tanrei.chnotchy.com/es/components/field/) con un [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/) dentro. Escribe tú los dos donde necesites algo que el campo no ofrece: algo tuyo entre la etiqueta y la caja, o debajo de la ayuda. La imagen, el nombre, la descripción y los estados son los mismos.

```html
<!-- El campo de cuadro combinado -->
<tanrei-combobox-field name="city" label="Ciudad" required required-text="Obligatorio"
  supporting-text="Adónde se envía el pedido." value="tokyo">
  <tanrei-option value="kyoto">Kioto</tanrei-option>
  <tanrei-option value="tokyo">Tokio</tanrei-option>
</tanrei-combobox-field>

<!-- Lo mismo, a mano: las propiedades del marco en el campo; todo lo demás, y las opciones, en el cuadro combinado -->
<tanrei-field label="Ciudad" required required-text="Obligatorio" supporting-text="Adónde se envía el pedido.">
  <tanrei-combobox name="city" value="tokyo">
    <tanrei-option value="kyoto">Kioto</tanrei-option>
    <tanrei-option value="tokyo">Tokio</tanrei-option>
  </tanrei-combobox>
</tanrei-field>
```

Lo que cambia es dónde está el control del formulario: a mano es el cuadro combinado, que recibe el `name`; en el campo de cuadro combinado es el campo.

## Especificaciones

### El campo

| Parte | Qué es |
| --- | --- |
| Etiqueta | La fila del campo encima del contenedor (`stacked`), o la etiqueta propia del cuadro combinado flotando dentro de él (`filled`, `outlined`). Es el nombre accesible, tanto si se dibuja como si se oculta con `labelHidden` |
| Marca de obligatoriedad | Después de la etiqueta: el tag de obligatoriedad en su forma de obligatorio, un asterisco o nada con `required`; el tag de obligatoriedad en su forma de opcional con `optional`. Una etiqueta flotante lleva el asterisco |
| Campo de entrada | El texto: lo que la persona escribe para encontrar una opción y, mientras no escribe, la etiqueta de la opción elegida o el valor propio. Una sola línea, que se desplaza |
| Marcador de posición | Una indicación que se muestra mientras el campo de entrada está vacío. Nunca es una etiqueta ni un valor |
| Icono inicial | El glifo del slot `leading-icon` o, si no lo hay, el de la opción elegida |
| Botón de borrar | Con `clearable`, mientras el texto no está vacío: vacía el texto y el valor |
| Chevron | Dice que el campo tiene una lista que se puede recorrer, y la abre y la cierra. No gira. Omítelo (`chevron` en false) donde solo hay sugerencias para lo que se ha escrito |
| Texto de apoyo | La fila del campo: una línea de ayuda. Mientras `error` es true, `errorText` ocupa su lugar (o va debajo de ella, donde el sistema de diseño conserva las dos). Las dos empiezan donde empieza el texto del campo de entrada |

La fila de la etiqueta, la marca y la fila de apoyo son del [campo](https://tanrei.chnotchy.com/es/components/field/) y se dibujan con los tokens del campo; todo lo demás es del [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/). Las tres variantes y los tres tamaños, `small` (32), `medium` (40) y `large` (56), son los del campo de texto. El sistema predeterminado solo incluye `stacked`.

Mientras la lista está abierta, la etiqueta y la ayuda se dibujan con foco junto con la caja, tenga o no el foco el campo de entrada.

### La lista

La lista se abre a una distancia de `comp.combobox.list.offset` por debajo del contenedor, exactamente con su mismo ancho, y por encima de él donde no hay sitio debajo. Es tan alta como sus filas hasta `list.max-height` (320), y a partir de ahí se desplaza.

| Parte | Qué es |
| --- | --- |
| Opción | Una fila con una etiqueta y, de forma opcional, una línea de apoyo y un glifo. La elegida tiene un relleno discreto y una marca de verificación |
| Coincidencia | Con `filter="contains"`, la parte de cada etiqueta que coincide con el texto se dibuja con más peso |
| Grupo | Una serie de opciones bajo un título opcional. Un grupo que el filtro deja vacío no se dibuja |
| Fila de estado | Después de las opciones: `statusText`, un indicador de carga mientras `status` es `loading`, el fallo mientras es `error`, o `emptyText` donde no hay ninguna coincidencia |

`filter="contains"` muestra las opciones cuya etiqueta contiene el texto, sin distinguir mayúsculas de minúsculas, el ancho de los caracteres ni los signos diacríticos de las letras. Con `filter="none"`, el cuadro combinado muestra todas las opciones que le das y filtras tú, con el evento `input`. El cuadro combinado nunca obtiene datos, espera, ordena ni clasifica.

### Escribir, moverse y elegir

| Entrada | Qué ocurre |
| --- | --- |
| Escribir | Edita el texto y abre la lista, filtrada. La primera coincidencia es la opción activa, y se lee cuando la escritura se detiene; con `allowCustomValue` no lo es ninguna |
| Flecha abajo, Flecha arriba, con la lista cerrada; el chevron | Abre la lista con todas las opciones. La opción activa es la elegida o, si no hay ninguna, la primera habilitada |
| Flecha abajo, Flecha arriba, con la lista abierta | La opción siguiente o la anterior, atravesando los grupos y dando la vuelta en los extremos (a través del texto, con `allowCustomValue`), salvo que `wrap` sea false |
| Av Pág, Re Pág | Diez opciones hacia abajo o hacia arriba |
| Inicio, Fin, Flecha izquierda, Flecha derecha | Mueven el cursor de texto |
| Enter, con una opción activa; una pulsación en una opción | La elige y cierra la lista. No envía el formulario |
| Enter, sin ninguna opción activa | Confirma el texto, emite `action` y envía el formulario, salvo que `action` se cancele |
| Escape | Cierra la lista abierta y conserva el texto. Pulsada otra vez, restablece el texto del valor confirmado. Nunca borra un valor |
| Tab; una pulsación fuera | Sale del campo: el texto se resuelve y la lista se cierra. La opción activa no se elige |
| Una pulsación en la etiqueta | Lleva el foco al campo de entrada y no abre nada. Mientras la lista está abierta, es una pulsación fuera del cuadro combinado: la lista se cierra y el foco se queda en el campo de entrada |

Al salir del campo, el texto se resuelve: el cuadro combinado decide qué valor representa ese texto. Un texto vacío vacía el valor. La etiqueta completa de una opción elige esa opción. Cualquier otro texto pasa a ser el valor con `allowCustomValue`, y sin él se descarta.

La lista no se abre al recibir el foco. Define tú `open` si quieres que lo haga.

Mientras un método de entrada está componiendo, todas las teclas le pertenecen. El Enter que confirma una conversión no elige ni envía nada.

`toggle` lleva el motivo de un cierre: `select`, `commit`, `escape`, `outside`, `press`, `tab`, `focus-out`, `anchor-hidden` o `empty`.

- Category: Text inputs
- Level: composed
- Listing: default
- Built from: Field, Combobox
- Page: https://tanrei.chnotchy.com/components/combobox-field/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/combobox-field.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | Variants left out: `filled`, `outlined`. |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element `<tanrei-combobox-field>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/combobox-field`).
- React: `ComboboxField` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-combobox-field` | lagging |
| SwiftUI | `TanreiComboboxField` | planned |
| Jetpack Compose | `TanreiComboboxField` | planned |
| Flutter | `TanreiComboboxField` | planned |
| React Native | `ComboboxField` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `value` (prop) | `value` | `selection` | `value` | `value` | `value` |
| `inputValue` (prop) | `inputValue` | `text` | `inputValue` | `controller` | `inputValue` |
| `label` (prop) | `label` | `label` | `label` | `labelText` | `label` |
| `labelHidden` (prop) | `labelHidden` | `labelsHidden` | `labelHidden` | `labelHidden` | `labelHidden` |
| `placeholder` (prop) | `placeholder` | `prompt` | `placeholder` | `hintText` | `placeholder` |
| `supportingText` (prop) | `supportingText` | `supportingText` | `supportingText` | `helperText` | `supportingText` |
| `error` (prop) | `error` | `error` | `isError` | `isError` | `error` |
| `disabled` (prop) | `disabled` | `disabled` | `enabled` | `enabled` | `disabled` |
| `required` (prop) | `required` | `isRequired` | `required` | `required` | `required` |
| `optional` (prop) | `optional` | `isOptional` | `optional` | `optional` | `optional` |
| `open` (prop) | `open` | `isPresented` | `expanded` | `menuController` | `open` |
| `chevron` (prop) | `noChevron` | `chevron` | `chevron` | `chevron` | `chevron` |
| `clearLabel` (prop) | `clearLabel` | `clearLabel` | `clearContentDescription` | `clearSemanticLabel` | `clearAccessibilityLabel` |
| `input` (event) | `input` | `text` | `onInputValueChange` | `onInputChanged` | `onInputValueChange` |
| `change` (event) | `change` | `selection` | `onValueChange` | `onChanged` | `onValueChange` |
| `toggle` (event) | `toggle` | `isPresented` | `onExpandedChange` | `onOpenChanged` | `onOpenChange` |
| `action` (event) | `action` | `onSubmit` | `keyboardActions` | `onSubmitted` | `onSubmitEditing` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `field`: The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose combobox floats the label it draws no label row.
- `combobox`: The combobox, as the Field's one control: the box and the text typed in it, the leading glyph, the clear button and the chevron, the list with its options, groups and status row, and the label that floats in the box in the looks that float one.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum`: `stacked`, `filled`, `outlined` | `"stacked"` | `variant` | The text input's three looks, so that a combobox is drawn as the text inputs beside it: stacked is a filled box that shows focus and error with a line inside its edge and draws no label of its own; filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. (From Combobox.) |
| `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. (From Combobox.) |
| `value` | `string` | `""` | `value` | The committed choice: the chosen option's value, or, with allowCustomValue, a text the person typed that names no option. Empty while nothing is chosen. It is one string, for ever: several values are another component. (From Combobox: Held by the combobox, which changes it by a choice, a commit or the clear button; the combobox field's is the same at every moment (CBF-3).) |
| `inputValue` | `string` | `""` | `input-value` | The text in the input. The combobox writes it as the person types and when a value is chosen or restored; the product may set it, and reads it from input to load options. (From Combobox: Held by the combobox, which writes it as the person types and when a value is chosen or restored; the combobox field's is the same at every moment (CBF-3).) |
| `label` | `string` | `""` | `label` | Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. (From Field: Names the combobox. In a filled or outlined look the combobox draws it, floating in its box, and the Field draws no label row (FLD-25, CMB-8).) |
| `labelHidden` | `boolean` | `false` | `label-hidden` | Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). (From Field: Hides the label wherever it would be drawn: the Field's row, or the combobox's floating label (FLD-25).) |
| `placeholder` | `string` | `""` | `placeholder` | A hint shown while the input is empty and no label is in the input line. Never a replacement for a name. (From Combobox.) |
| `supportingText` | `string` | `""` | `supporting-text` | Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). (From Field.) |
| `errorText` | `string` | `""` | `error-text` | Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. (From Field.) |
| `error` | `boolean` | `false` | `error` | Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. (From Field: Puts the Field in its error condition, which puts the combobox in its own (FLD-8, CMB-10).) |
| `disabled` | `boolean` | `false` | `disabled` | Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. (From Field: Disables the Field, which disables the combobox (FLD-14, CMB-46).) |
| `readOnly` | `boolean` | `false` | `readonly` | The value is shown, can be focused, selected and copied, and is submitted, but cannot be changed: the list does not open and neither the chevron nor the clear button is drawn. (From Combobox.) |
| `required` | `boolean` | `false` | `required` | What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. (From Field.) |
| `optional` | `boolean` | `false` | `optional` | Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. (From Field.) |
| `requiredMark` | `enum`: `auto`, `tag`, `asterisk`, `none` | `"auto"` | `required-mark` | How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. (From Field.) |
| `requiredText` | `string` | `""` | `required-text` | The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. (From Field.) |
| `optionalText` | `string` | `""` | `optional-text` | The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. (From Field.) |
| `open` | `boolean` | `false` | `open` | Whether the list is shown. The combobox opens and closes itself and emits toggle; the product may also set it (to open on focus, for one). Ignored while the combobox is disabled or read-only or has nothing to show. (From Combobox: Held by the combobox, which opens and closes its list itself; the combobox field's is the same at every moment (CBF-3).) |
| `allowCustomValue` | `boolean` | `false` | `allow-custom-value` | False: the value is always one of the options, and a text that names none is given up when the person leaves. True: the options are suggestions, and a text that names none becomes the value as typed (a font family, a tag, an address). (From Combobox.) |
| `filter` | `enum`: `contains`, `none` | `"contains"` | `filter` | Who decides which options answer the text. contains: the combobox shows the options whose label contains what was typed, ignoring case, and marks the match. none: the combobox shows every option it is given and the product filters — on input, from its own data or a server — and says what it is doing with status. (From Combobox.) |
| `wrap` | `boolean` | `true` | `no-wrap` (turns it off) | Whether the arrow keys go round at the ends of the list: Down Arrow on the last option to the first, Up Arrow on the first to the last — with allowCustomValue true, through the text itself, where no option is active (CMB-26). False stops them at the ends. (From Combobox.) |
| `chevron` | `boolean` | `true` | — | Draws the chevron that opens the whole list without typing. False for a field whose suggestions exist only for what was typed (a remote search): there is no list to look through. (From Combobox.) |
| `clearable` | `boolean` | `false` | `clearable` | Draws a clear button while the text is not empty, for a combobox whose value may be none. Without it, emptying the text and leaving the field clears the value. (From Combobox.) |
| `clearLabel` | `string` | `""` | `clear-label` | The clear button's accessible name, in the product's language ("Clear"). Required while clearable is true. (From Combobox.) |
| `status` | `enum`: `idle`, `loading`, `error` | `"idle"` | `status` | What the product's source of options is doing, which the product sets: idle (the options given are final), loading (options are on their way: the status row shows a loading indicator), error (the source failed: the status row shows statusText in the error color). (From Combobox.) |
| `statusText` | `string` | `""` | `status-text` | The status row's text, in the product's language, announced to assistive technology when it changes: a count ("12 of 340 shown"), that loading failed, or, while status is loading, the loading indicator's name ("Loading options"). (From Combobox.) |
| `emptyText` | `string` | `""` | `empty-text` | Shown in the list while the text names nothing the combobox can show, allowCustomValue is false and no status is set, in the product's language ("No matches"). The product's: Tanrei has no words for it. Empty reads the product's words; with neither, no such row is drawn and it is reported (CMB-32). (From Combobox.) |
| `separation` | `enum`: `auto`, `divider`, `gap` | `"auto"` | `separation` | How a group of options is told from what is next to it. divider: a line between them. gap: empty space and no line. Auto takes comp.combobox.separation, which follows the design system's choice. (From Combobox.) |
| `iconSpace` | `enum`: `auto`, `always`, `never` | `"auto"` | `icon-space` | Whether a shown option keeps the room of the leading icon column where it has no icon, so that the labels of a section start on one line — a section being the shown options of a group, or a run of adjacent shown options outside any group. auto: an option keeps the column while another shown option of its section has a leading icon; an option the filter hides does not count. always: every option keeps it. never: only an option that has an icon has the column. The menu's and the select's iconSpace, with the same values and default (CMB-67). (From Combobox.) |
| `density` | `enum`: `regular`, `compact` | `"regular"` | `density` | How much room an option of the list takes: its least height, its paddings, the gap between its columns and the size of its glyphs (the leading icon, the check), and never its text style. regular (a 48 row in the default system) is for a product used by touch as well as by pointer; compact (a 32 row with 20 glyphs, the menu's compact row) is for a tool used with a pointer, whose lists are long. For touch an option is never lower than the touch target in either (CMB-34). The field's own box is not changed: its height is size's. A design system may add values. (From Combobox.) |

### Events

| Event | Description |
| --- | --- |
| `input` | The person changed the text (typing, deleting, pasting, dictating, the clear button, Escape restoring it); carries the new text. Not emitted when the product sets inputValue or value, or when a choice writes its label. It is the product's cue to load options; the combobox does not delay or drop it. (From Combobox.) |
| `change` | The committed value changed by the person: an option was chosen, a custom text was committed, or the value was cleared; carries the new value and the text now shown. Not emitted when the product sets value, when the chosen option is chosen again, or while the person only types or moves through the list. (From Combobox.) |
| `toggle` | The list was opened or closed by the person or by having nothing left to show; carries the new open and, for a close, the reason: select, commit, escape, back, outside, press, tab, focus-out, anchor-hidden or empty (in the platform's casing). After a choice it follows change. (From Combobox.) |
| `action` | The person pressed Enter with no option active and the text was committed; emitted after any change it caused. On the web it is followed by the form's submission unless cancelled. (From Combobox.) |

### Slots

| Slot | Description |
| --- | --- |
| `leading-icon` | A glyph at the start of the container that stands for the combobox whatever is chosen (a magnifier before a field that searches people). It takes the place of the chosen option's own glyph. (From Combobox.) |
| `label-icon` | A glyph before the label. (From Field.) |

### Item: `option`

One choice of the combobox: a label, the value it stands for, and optionally a supporting line and a glyph. The same kind a select holds.

Names: Web `tanrei-option`, SwiftUI `TanreiComboboxOption`, Jetpack Compose `TanreiComboboxOption`, Flutter `TanreiComboboxOption`, React Native `ComboboxOption`.

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `""` | `label` | The option's text and its accessible name: what the filter searches and what the input shows once the option is chosen. Required. |
| `value` | `string` | `""` | `value` | Identifies the choice: the option is the chosen one while the combobox's value equals it. Unique within the combobox and not empty: the empty value means that nothing is chosen. |
| `supportingText` | `string` | `""` | `supporting-text` | A line below the label that says more about the choice. Shown in the list, not in the input; not searched. |
| `leadingIcon` | `string` | `""` | `leading-icon` | The name of an icon (a glyph of the system's icon set) before the label; the container shows it too while the option is chosen and the combobox has no leading icon of its own. |
| `disabled` | `boolean` | `false` | `disabled` | Prevents the option from being chosen. It stays reachable with the arrow keys. |

### Item: `option-group`

A run of related options, optionally titled. The combobox separates a group from what is next to it by a divider or a gap, and draws neither a group nor its title while the filter leaves it empty.

Names: Web `tanrei-option-group`, SwiftUI `TanreiComboboxSection`, Jetpack Compose `TanreiComboboxGroup`, Flutter `TanreiComboboxGroup`, React Native `ComboboxOptionGroup`.

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | `""` | — | A short heading drawn above the group's options, which also names the group; empty draws none and leaves the group unnamed. |

### States

`enabled`, `disabled`, `hovered`, `focused`, `pressed`, `selected`, `error`, `loading`

### Accessibility

- Role: `combobox`
- Labeling: The combobox field adds nothing to what its members expose and coordinates nothing: the Field gives the combobox its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the combobox carries them on its own input, with its expanded state, its list and its active option (CMB-12, CMB-48). Assistive technology meets one editable combobox named by label, with a list of the same name, exactly as it meets a Field around a combobox written by hand.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Every key | The combobox's (its accessibility block; CMB-16, CMB-20, CMB-21, CMB-26 to CMB-30). The combobox field handles no key and adds no focus stop (CBF-5). |

- One level down is the same thing: a Field with a combobox in it, holding the same options. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (CBF-1).
- The options are the product's, and they are the combobox's: the combobox field passes them on and does nothing with them (CBF-2). Value, text and open are the combobox's too, and the combobox field keeps no second copy that could disagree with it (CBF-3).
- On the web the two members stand in the combobox field's own shadow root, so the form meets the combobox field and not the combobox (CBF-4); focus passes through to the input (CBF-5); and the product's option elements stay its own children, read by the combobox through a slot.
- A list is not a second thing the component reports: choosing an option is setting its one value, so the combobox field is composed, not a feature.

### Behaviour

Requirements in EARS form, each with its stable id.

- **CBF-1** THE combobox field SHALL be a Field that frames one combobox, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its combobox, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon slot for its combobox; SHALL give its options to its combobox (CBF-2); and SHALL emit its combobox's events as its own, each once. THE combobox field SHALL be as wide as the place it stands in, and its combobox SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (CMB-49). It SHALL draw no part of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that combobox do when a product places the one in the other (FLD-1 to FLD-28; CMB-1 to CMB-62) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, CMB-7, CMB-8); the supporting row and the error (FLD-7 to FLD-9, FLD-26, CMB-10); the name, the description and the states (FLD-10, FLD-11, FLD-14, CMB-12, CMB-46); and the list, which is the combobox's alone and as wide as its container (CMB-22).
- **CBF-2** THE combobox field SHALL take the options and the option groups a product gives it — in the platform's form for a combobox's own (its child elements on the web) — and give them to its combobox as that combobox's options, in the order given, each with its label, its value, its supporting text, its leading icon and its disabled, and each group with its title: the option a product wrote SHALL be the option its combobox reads, never a copy of it. THE combobox field SHALL NOT read, filter, order, count or keep an option, and SHALL make no option active or chosen: which options are shown, which is active and which is the chosen one are its combobox's (CMB-25, CMB-26, CMB-36). WHEN the product adds, removes, reorders or changes an option or a group THE combobox field's combobox SHALL meet the change at once and as CMB-31 says, as though the product had changed that combobox's own options.
- **CBF-3** THE combobox field SHALL hold no value, no text and no open state of its own: its value, its inputValue and its open SHALL at every moment be its combobox's. WHEN its combobox changes one of them — a choice, a commit or the clear button (CMB-17, CMB-20, CMB-27 to CMB-29); typing, or a text the combobox writes itself for a choice, for a commit that was given up or for Escape (CMB-16, CMB-27, CMB-29, CMB-30); the list opening or closing, or open taken back because there is nothing to show (CMB-21, CMB-30, CMB-57) — THE combobox field's SHALL be the new one before any event that reports the change is emitted, and equally WHERE no event reports it. WHEN the product sets one on the combobox field THE combobox field SHALL set it on its combobox and nothing else, so that no event follows (CMB-31).
- **CBF-4** WHERE the platform has forms (the web) THE combobox field SHALL be the one control the form sees: it SHALL take name, submit its combobox's value — never the text of an edit that was not committed — reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its combobox would report there (CMB-59), and be left out WHILE disabled is true or a disabled group of the form holds it; its combobox and its Field SHALL take no part in the form themselves. WHEN Enter asks for the form's submission (CMB-28) the form asked SHALL be the combobox field's own, through that form's default button (BTN-30), and not WHEN action was cancelled.
- **CBF-5** WHEN the combobox field is given focus — by the product, by a press on any part of it that FLD-12 or CMB-14 gives to the input, or by a form that reports its validity — THE combobox field SHALL pass the focus to its combobox's input and SHALL add no stop to the focus order: the stops inside it are its combobox's, in that combobox's order (the input, then the clear button while it is shown). WHILE focus is anywhere inside it, or its combobox's list is open, its Field's rows SHALL be drawn focused, because its combobox says so to its Field (FLD-13, CMB-61): the combobox field arranges nothing for it. A press on its Field's label row WHILE the list is open is a press outside the combobox: the list SHALL close with the reason outside, choosing nothing (CMB-30), and focus SHALL go to the input (FLD-12).
- **CBF-6** IF the combobox field is placed in a Field THE combobox field SHALL in debug builds report that it is a field already and that the bare control is the combobox, and both SHALL still render (FLD-15). WHILE it stands in a field group THE combobox field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
- **CBF-7** THE combobox field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), emptyText and clearLabel by its combobox (CMB-60), each from the instance's prop and then from the product's words.
- **CBF-8** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE combobox field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the combobox field is invalid — except those the combobox field owns (aria-label, aria-labelledby, aria-disabled, aria-haspopup, aria-expanded, aria-controls), which it SHALL move and not expose: its name is label (CBF-1). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE combobox field SHALL take it off that element. WHEN the product sets an aria- attribute the combobox field owns THE combobox field SHALL report it in debug builds.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.field.…` → `--tanrei-comp-field-…`).

#### `tanrei.comp.field`

| Token | Type | Value |
| --- | --- | --- |
| `comp.field.label.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.label.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.label-icon.size` | `dimension` | `{tanrei.sys.icon.small}` |
| `comp.field.label-icon.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.mark` | `number` | `{tanrei.sys.behavior.requirement-mark}` |
| `comp.field.requirement.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.asterisk-gap` | `dimension` | `{tanrei.sys.space.space25}` |
| `comp.field.supporting-text.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` |
| `comp.field.supporting-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.counter.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` |
| `comp.field.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` |
| `comp.field.standard.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.error.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error-text.color` | `color` | `{tanrei.sys.color.error}` |
| `comp.field.value-text.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.value-text.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.error-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.error-text.placement` | `number` | `0` |

Per-state tokens, valued by the design system's pattern rules (not written by hand):

- `comp.field.<variant>.<state>.<property>` for the variants `standard`, the states `focused`, `disabled` and the properties `label.color`, `label-icon.color`, `supporting-text.color`, `required-asterisk.color`, `error.label.color`, `error.label-icon.color`, `error.supporting-text.color`, `error.required-asterisk.color`, `counter.color`, `error.counter.color`, `value-text.color`, `error.value-text.color`, `error-text.color`.

### Qué dibuja la web de otra manera

- `<tanrei-option>` y `<tanrei-option-group>` son datos: no dibujan nada. Son los elementos que contiene un select. Una opción cuyo valor es la cadena vacía se dibuja y no se puede elegir, porque el valor vacío significa que no hay nada elegido.
- El shadow root del elemento contiene un `<tanrei-field>` alrededor de un `<tanrei-combobox>`. Tus hijos `<tanrei-option>` siguen siendo hijos suyos y llegan al cuadro combinado a través de un slot; nada se mueve ni se copia.
- El campo de cuadro combinado es un elemento asociado a formularios: el único control que ve el formulario. Recibe `name`, envía `value` y nunca el texto de una edición que no se confirmó, se restablece al valor del atributo `value` y, mientras `required` y `value` está vacío, notifica al formulario que falta un valor. Enter sin ninguna opción activa envía su formulario.
- `value`, `inputValue` y `open` son en todo momento los del cuadro combinado: cada uno es ya el nuevo en todos los listeners.
- `chevron` y `wrap` son los atributos inversos `no-chevron` y `no-wrap`, y `readOnly` es `readonly`.
- `input` es el evento nativo del elemento de texto. `change` y `action` llevan `detail.value` y `detail.inputValue`. Los cuatro eventos son los propios del cuadro combinado, con el campo de cuadro combinado como destino; `toggle` no se propaga.
- `focus()` va al campo de entrada. El elemento no puede recibir el foco por sí mismo y no tiene rol: dale nombre con `label`, nunca con `aria-label`.
- Partes: `field` y `combobox` son los dos miembros; las partes de cada miembro se exportan con sus propios nombres, y `label` y `requirement-label` también como `field-label`, `combobox-label`, `field-requirement-label` y `combobox-requirement-label`.
- Un solo campo se diferencia con una propiedad personalizada definida en él: `--tanrei-comp-field-*` para las filas, `--tanrei-comp-input-box-*` para la caja, `--tanrei-comp-combobox-*` para la lista.
- La lista es un elemento `popover="manual"` en la capa superior. Una pulsación fuera la cierra y además llega al elemento que hay debajo.
- La fila de estado queda debajo de las opciones y no se desplaza con ellas, de modo que un recuento o un fallo se mantienen a la vista.
- Antes de que el elemento esté definido, sus opciones son texto corrido. Oculta `tanrei-combobox-field:not(:defined) > *` y reserva la altura.
- La web no tiene un gesto de retroceso propio, así que `toggle` nunca lleva el motivo `back`.

## Pautas

### Campo de cuadro combinado, select, búsqueda o un campo de texto

| Aspecto | Campo de cuadro combinado | Select | Búsqueda | Campo de texto |
| --- | --- | --- | --- | --- |
| Contiene | Un valor que se encuentra escribiendo | Un valor de una lista cerrada | Una consulta | Cualquier texto |
| Muestra las opciones | A medida que la persona escribe | Tras una pulsación | Sugerencias y resultados | No |
| Acepta un valor que no está en la lista | Con `allowCustomValue` | No | Sí | Sí |
| Forma parte de un formulario | Sí | Sí | No | Sí |

1. Con hasta unas cinco opciones cortas, muéstralas todas: botones de opción.
2. Si la lista es lo bastante corta para recorrerla con la vista, y cerrada, es un select.
3. Si las personas prefieren escribir a desplazarse, o si el campo acepta un valor que no está en la lista, es un campo de cuadro combinado.
4. Si escribir lleva a lugares a los que ir y no a un valor, es una búsqueda.
5. Varios valores son otro componente: un cuadro combinado guarda uno solo.
6. Si la etiqueta está en otro lugar —un filtro en una barra de herramientas, una celda de una tabla—, es el [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/) sin nada más, que recibe su nombre de su propio `label`.

### Recomendado

- Escribe una etiqueta que nombre lo que se elige, y mantenla visible en un formulario.
- Usa `allowCustomValue` solo donde un valor que no está en la lista sea una respuesta real.
- Da `clearable` a un campo de cuadro combinado cuyo valor pueda ser ninguno, y da nombre al botón con `clearLabel`.
- Cuando cargues opciones, define `status` y `statusText` para que la lista diga que está esperando, cuántas muestra o que ha fallado.
- Da `emptyText`, en el campo de cuadro combinado o una sola vez para todo el producto con `setWords({ emptyText })`. Tanrei no incluye textos propios: sin él, un texto que no coincide con nada no dibuja ninguna fila, y la lista no tiene nada que mostrar.

### Evita

- No uses el marcador de posición como etiqueta. Desaparece en cuanto la persona escribe.
- No guardes, navegues ni envíes con `input`. Se emite con cada pulsación de tecla; `change` es el valor confirmado.
- No trates un texto que no nombra ninguna opción como un error del campo. Se descarta cuando la persona sale. Si quieres decir «elige una opción de la lista», define tú `error` y `errorText`.
- No pongas un campo de cuadro combinado dentro de un campo. Ya es un campo; el control que un campo enmarca es el [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/).
- No abras la lista al recibir el foco en un formulario de muchos campos: en cada parada tapa los campos de debajo.

## Accesibilidad

### De qué se encarga el componente

- El campo de entrada es un cuadro combinado editable con un cuadro de lista. Su nombre es `label`, tanto si se dibuja como si se oculta, y nunca el marcador de posición. El campo se lo da al cuadro combinado, que lo lleva en su propio campo de entrada.
- El texto de apoyo o de error que se muestra es su descripción, junto con `optionalText` mientras el campo es opcional.
- Un error que aparece mientras el foco está en el campo se anuncia una vez, de forma cortés.
- Se expone como no válido mientras `error` es true, como obligatorio mientras `required` está activado, como de solo lectura, y como expandido mientras su lista está abierta.
- El foco permanece en el campo de entrada mientras la lista está abierta. La opción activa es su descendiente activo, de modo que escribir nunca deja de editar el texto. Una opción que la escritura convirtió en activa se señala cuando la escritura se detiene medio segundo, para que un lector de pantalla lea primero la letra escrita y después la opción que elegiría Enter; una opción a la que llevan las teclas de flecha se señala al instante.
- La lista es un cuadro de lista que recibe su nombre de la etiqueta. Cada opción tiene su nombre, su descripción, si es la elegida, si está deshabilitada y su posición entre las opciones que se muestran. Un grupo recibe su nombre de su título.
- Una coincidencia se marca con el peso, nunca solo con el color. La etiqueta se lee como un solo texto.
- La fila de estado es una región activa (live region): su texto se lee de forma cortés cuando cambia, y de inmediato cuando la fuente de datos ha fallado. Durante la carga, la lista se marca como ocupada y no se anuncia nada.
- Mientras un método de entrada está componiendo, el cuadro combinado no atiende ninguna tecla.
- El chevron es un botón para el puntero y para la exploración táctil, fuera del orden del foco. El teclado abre la lista con Flecha abajo.
- El botón de borrar es un botón que recibe su nombre de `clearLabel`, y es la siguiente parada del foco después del campo de entrada.
- Escape cierra la lista y no va más allá, de modo que un diálogo que rodee al cuadro combinado permanece abierto.
- El área de pulsación del campo cumple el objetivo mínimo, y las opciones son al menos tan altas como el objetivo mínimo.
- Con el texto al 200%, la etiqueta, la ayuda, las opciones, los títulos y la fila de estado saltan de línea. Solo el texto del campo de entrada se queda en una línea, y se desplaza.
- Con colores forzados, el campo y la lista ganan un borde, la opción activa toma los colores de resaltado y la opción elegida se muestra con su marca de verificación.
- En un diseño de derecha a izquierda, el campo y cada fila se reflejan, y cada texto conserva su propia dirección. El chevron, el glifo del botón de borrar y la marca de verificación no se reflejan.

Carencias conocidas en la web:

- El divisor entre dos grupos no se expone como separador: un cuadro de lista solo contiene opciones y grupos.
- El filtro iguala mayúsculas, ancho y signos diacríticos del mismo modo en todos los sistemas de escritura. No encuentra el hangul por su consonante inicial ni el kana por su lectura.
- Antes de que el elemento esté definido, las opciones son texto en la página, sin ningún control.

### Qué debes hacer tú

- Da un `label` a cada campo de cuadro combinado, y a cada opción una etiqueta y un valor que no esté vacío.
- Da un `clearLabel` a un campo de cuadro combinado que se pueda borrar.
- Escribe `statusText` en el campo de cuadro combinado. Da `emptyText`, `requiredText`, `optionalText` y `clearLabel` en el campo de cuadro combinado, o una sola vez para todo el producto con `setWords()`. Tanrei no incluye textos propios; si falta uno, se notifica en desarrollo. Consulta [Los textos del producto](https://tanrei.chnotchy.com/es/foundations/words/).
- Valida tú el valor, activa `error` y escribe `errorText` de modo que diga cómo corregir la respuesta.
- Mantén únicos los valores de las opciones dentro de un campo de cuadro combinado.