---
title: "Campo de selección"
description: "Permite elegir un valor de una lista cerrada como un campo completo de un formulario. Una etiqueta que puede decir que el campo es obligatorio u opcional, un activador que muestra la opción elegida y abre una lista de opciones, y una línea de ayuda o un error debajo, todo ello vinculado para la tecnología de apoyo y presente en un formulario como un solo control."
url: "https://tanrei.chnotchy.com/es/components/select-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Campo de selección

> Permite elegir un valor de una lista cerrada como un campo completo de un formulario. Una etiqueta que puede decir que el campo es obligatorio u opcional, un activador que muestra la opción elegida y abre una lista de opciones, y una línea de ayuda o un error debajo, todo ello vinculado para la tecnología de apoyo y presente en un formulario como un solo control.

## Descripción general

Usa un campo de selección en un formulario para elegir un valor de una lista conocida y cerrada: un país, una zona horaria, un plan. Es el caso corriente, listo para usarse: una etiqueta, la caja que muestra la opción elegida y abre la lista, una línea de ayuda y las palabras para un valor que se rechazó.

**Se compone de** un [campo](https://tanrei.chnotchy.com/es/components/field/) y un [select](https://tanrei.chnotchy.com/es/components/select/). El campo es el marco: la etiqueta, la marca de obligatorio o de opcional, la ayuda y el error. El select es el control: el activador, la lista y todo lo que la persona hace en ellos. El campo de selección 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 select.

Es tan ancho como el lugar en el que se pone, y su caja lo llena. Para una caja más estrecha, dale un lugar más estrecho.

En la web es `<tanrei-select-field>`, con elementos `<tanrei-option>` como hijos. Las demás plataformas todavía no lo han implementado.

### Uso

Las opciones son hijos del campo de selección: cada una tiene un valor y una etiqueta. `value` dice cuál es la elegida. `change` y `toggle` son los eventos del propio select, y cuando se oye cualquiera de los dos, el `value` y el `open` del campo ya son los nuevos.

**Web**

```html
<form>
  <tanrei-select-field name="country" label="País" value="jp" required required-text="Obligatorio"
    supporting-text="El país al que van dirigidas tus facturas.">
    <tanrei-option value="ca">Canadá</tanrei-option>
    <tanrei-option value="jp">Japón</tanrei-option>
  </tanrei-select-field>
</form>

<!-- Agrupado, con una línea debajo de una etiqueta y un glifo que representa al campo. -->
<tanrei-select-field label="Zona horaria" value="Europe/Lisbon">
  <span slot="leading-icon">public</span>
  <tanrei-option-group label="Asia">
    <tanrei-option value="Asia/Tokyo" supporting-text="UTC+9">Tokio</tanrei-option>
  </tanrei-option-group>
  <tanrei-option-group label="Europa">
    <tanrei-option value="Europe/Lisbon" supporting-text="UTC+0">Lisboa</tanrei-option>
  </tanrei-option-group>
</tanrei-select-field>

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

  const country = document.querySelector('[name="country"]');
  // La persona eligió otra opción. El valor ya es el nuevo.
  country.addEventListener('change', () => save(country.value));
  // La persona abrió o cerró la lista; un cierre dice por qué.
  country.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
  // La validación es tuya: el campo de selección nunca define error por sí mismo.
  country.error = submitted && !ships(country.value);
  country.errorText = 'Todavía no hacemos envíos a ese país. Elige otro país.';
</script>
```

**React**

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

<SelectField label="País" value={country} required requiredText="Obligatorio" onChange={(event) => setCountry(event.currentTarget.value)}>
  <Option value="ca">Canadá</Option>
  <Option value="jp">Japón</Option>
</SelectField>
```

### Un nivel más abajo

El mismo campo, escrito a mano con sus dos miembros, es la misma imagen y el mismo control para la tecnología de apoyo:

```html
<tanrei-field label="País" required required-text="Obligatorio"
  supporting-text="El país al que van dirigidas tus facturas.">
  <tanrei-select name="country" placeholder="Elige un país">
    <tanrei-option value="jp">Japón</tanrei-option>
    <tanrei-option value="ke">Kenia</tanrei-option>
  </tanrei-select>
</tanrei-field>
```

Baja a ese nivel cuando necesites una organización que el campo de selección no ofrezca:

| Necesitas | Usa |
| --- | --- |
| Una etiqueta, la caja, ayuda y un error | El campo de selección |
| Algo tuyo dentro del marco, junto a la caja o debajo de ella | Un [campo](https://tanrei.chnotchy.com/es/components/field/) con un [select](https://tanrei.chnotchy.com/es/components/select/) y tu propio elemento dentro |
| La caja sin nada más, donde su etiqueta está en otro lugar: un tema en una barra, un criterio de ordenación en una barra de herramientas, una celda de una tabla | El [select](https://tanrei.chnotchy.com/es/components/select/) sin nada más, con su propio `label` como nombre |
| Una lista tan larga que las personas prefieren escribir a desplazarse | Un [cuadro combinado](https://tanrei.chnotchy.com/es/components/combobox/) |

Lo que cambia un nivel más abajo es dónde se dicen las cosas. `name`, `value` y las opciones están en el select, que es entonces el control que encuentra el formulario, y sus eventos se oyen en él. `label`, `error` y `disabled` se quedan en el campo, que los pasa al control: no definas los del propio select.

## Especificaciones

### Qué aporta cada miembro

| Aspecto | Del campo | Del select |
| --- | --- | --- |
| Propiedades | `label`, `labelHidden`, `supportingText`, `errorText`, `error`, `disabled`, `required`, `optional`, `requiredMark`, `requiredText`, `optionalText` | `variant`, `size`, `value`, `placeholder`, `readOnly`, `open`, `separation`, `iconSpace`, `status`, `statusText`, `emptyText` |
| Eventos | — | `change`, `toggle` |
| Slots | `label-icon` | `leading-icon`, y las opciones |
| Tokens | `comp.field.*` | `comp.input-box.*` para la caja, que leen todas las cajas de entrada; `comp.select.*` para la lista |

El select tiene un `label`, un `labelHidden`, un `error` y un `disabled` propios. No son propiedades del campo de selección: el `label` del campo da nombre al control, su `error` pone la caja en su estado de error y su `disabled` la deshabilita. Así, defines cada uno una sola vez, en el campo de selección, y su etiqueta cambia con el control.

En el aspecto `stacked`, la etiqueta es la fila del campo situada sobre la caja. En los aspectos `filled` y `outlined`, el select dibuja él mismo esa etiqueta, flotando en su caja, y el campo no dibuja ninguna fila de etiqueta; un campo obligatorio se marca entonces con un asterisco después de la etiqueta, sea cual sea la marca que indique el sistema de diseño. La ayuda empieza donde empieza el valor, después de un icono inicial. Mientras la lista está abierta, la etiqueta y la ayuda se dibujan con foco, igual que la caja.

Lo que hacen el activador y la lista (abrirse, las teclas de flecha, la escritura, la elección, los grupos) está en la [página del select](https://tanrei.chnotchy.com/es/components/select/). Lo que hace el marco (la marca de obligatorio, la ayuda, el error y cómo se anuncia) está en la [página del campo](https://tanrei.chnotchy.com/es/components/field/).

### Diferenciar un solo campo

El campo de selección no tiene ningún token propio. Su marco lee los tokens del campo, y su caja y su lista leen los del select, se definan donde se definan. Para cambiar una sola instancia, define en ella el token del miembro:

```html
<tanrei-select-field label="País"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-select-field>
```

- Category: Selection
- Level: composed
- Listing: default
- Built from: Field, Select
- Page: https://tanrei.chnotchy.com/components/select-field/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/select-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-select-field>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/select-field`).
- React: `SelectField` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-select-field` | lagging |
| SwiftUI | `TanreiSelectField` | planned |
| Jetpack Compose | `TanreiSelectField` | planned |
| Flutter | `TanreiSelectField` | planned |
| React Native | `SelectField` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `value` (prop) | `value` | `selection` | `value` | `value` | `value` |
| `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` | `controller` | `open` |
| `change` (event) | `change` | `selection` | `onValueChange` | `onChanged` | `onValueChange` |
| `toggle` (event) | `toggle` | `isPresented` | `onExpandedChange` | `onOpenChanged` | `onOpenChange` |

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 select floats the label it draws no label row.
- `select`: The select, as the Field's one control: the trigger with the value it shows, its leading icon and its chevron, the label that floats in it in the looks that float one, and the list of options that opens from it.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum`: `stacked`, `filled`, `outlined` | `"stacked"` | `variant` | The text input's three looks, so that a select 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: the label of the Field that frames it stands above it. 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 Select.) |
| `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. The text input's three sizes: medium and large for forms, small for a select in an app bar, a toolbar or a dense row of controls, where nothing frames it. The hit area always meets the minimum target. A design system may add values. (From Select.) |
| `value` | `string` | `""` | `value` | The value of the chosen option. The select shows that option's label; while value names no option it shows the placeholder. An option whose value is the empty string is a choice like any other ("None", "Any") and is the chosen one while value is empty. (From Select.) |
| `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 select. In a filled or outlined look the select draws it, floating in its box, and the Field draws no label row (FLD-25, SEL-15).) |
| `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 select's floating label (FLD-25).) |
| `placeholder` | `string` | `""` | `placeholder` | A hint shown while nothing is chosen and the label is not in the line ("Choose a country"). Never a replacement for label, and never a choice. (From Select.) |
| `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: The Field puts its select in the select's own error condition (FLD-8, SEL-9).) |
| `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: The Field disables its select (FLD-14, SEL-46); the select field is then left out of its form (SEF-2).) |
| `readOnly` | `boolean` | `false` | `readonly` | The value is shown, can be focused and is submitted, but cannot be changed: the list does not open and no chevron is drawn. (From Select.) |
| `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: The Field exposes its select as required (FLD-10, SEL-11).) |
| `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 select opens and closes itself and emits toggle; the product may also set it. Ignored while the select is disabled or read-only or has nothing to show: no option, no status row and no empty text (SEL-61). (From Select.) |
| `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.select.separation, which follows the design system's choice. (From Select.) |
| `iconSpace` | `enum`: `auto`, `always`, `never` | `"auto"` | `icon-space` | Whether an 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 an option group, or a run of adjacent options outside any group. auto: an option keeps the column while another option of its section has a leading icon, so that a section without icons starts its labels where the row's content starts. always: every option keeps it. never: only an option that has an icon has the column. The menu's iconSpace, with the same values and default (SEL-66). (From Select.) |
| `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 (SEL-37). The field's own box is not changed: its height is size's. A design system may add values. (From Select.) |
| `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 and the list is marked busy) or error (the source failed: the status row shows statusText in the error color, announced at once). The combobox's and the search's values, with the same meaning. The select never loads anything itself. (From Select.) |
| `statusText` | `string` | `""` | `status-text` | The status row's text, in the product's language, read to assistive technology when the list opens and when it changes: a count ("20 of 340 projects shown"), that loading failed ("Projects could not be loaded"), or, while status is loading, the loading indicator's name ("Loading projects"). Empty draws no status row unless status is loading. (From Select.) |
| `emptyText` | `string` | `""` | `empty-text` | Shown in the list while the select holds no option, status is idle and statusText is empty, in the product's language ("No projects yet"), so that the select still opens and says why there is nothing to choose. The product's: Tanrei has no words for it. Empty reads the product's words (noOptionsText); with neither, the select has nothing to show and does not open (SEL-61), and it is reported. (From Select.) |

### Events

| Event | Description |
| --- | --- |
| `change` | The person chose an option whose value differs from the select's; carries the new value. Not emitted when the product sets value, when the chosen option is chosen again, or while the person only moves through the list. (From Select.) |
| `toggle` | The list was opened or closed by the person; carries the new open and, for a close, the reason: select, escape, back, outside, focus-out, anchor-hidden, press or tab (in the platform's casing). After a choice it follows change. (From Select.) |

### Slots

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

### Item: `option`

One choice of the select: a label, the value it stands for, and optionally a supporting line and a glyph.

Names: Web `tanrei-option`, SwiftUI `TanreiSelectOption`, Jetpack Compose `TanreiSelectOption`, Flutter `TanreiSelectOption`, React Native `SelectOption`.

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `""` | `label` | The option's text and its accessible name; the container shows it once the option is chosen. Required. |
| `value` | `string` | `""` | `value` | Identifies the choice: the option is the chosen one while the select's value equals it. Unique within the select. The empty string is a value like any other, for an option that stands for no choice ("None"). |
| `supportingText` | `string` | `""` | `supporting-text` | A line below the label that says more about the choice. Shown in the list, not in the container. |
| `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 select 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 select separates a group from what is next to it by a divider or a gap.

Names: Web `tanrei-option-group`, SwiftUI `TanreiSelectSection`, Jetpack Compose `TanreiSelectGroup`, Flutter `TanreiSelectGroup`, React Native `SelectOptionGroup`.

| 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`

### Accessibility

- Role: `combobox`
- Labeling: The select field adds nothing to what its members expose and coordinates nothing: the Field gives the select its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the select carries them on its own trigger and names its list by the same name (SEL-11, SEL-48). Assistive technology meets one control that opens a list of choices, named by label, with the chosen option's label as its value — exactly as it meets a Field around a select written by hand.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Every key | The select's (its accessibility block; SEL-23, SEL-27, SEL-28, SEL-31, SEL-33, SEL-34). The select field handles no key and adds no focus stop (SEF-3). |

- One level down is the same thing: a Field with a select in it, holding the same options. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (SEF-1).
- On the web the two members stand in the select field's own shadow root, so the form meets the select field and not the select (SEF-2), focus passes through to the trigger (SEF-3), and the options, which stay the product's children, reach the select through a slot and are read by it as data.
- A select with no visible label of its own — in a header, a toolbar, a column of a table — is the bare select, named by its own label, not a select field with labelHidden.

### Behaviour

Requirements in EARS form, each with its stable id.

- **SEF-1** THE select field SHALL be a Field that frames one select, 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 select, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon slot for its select; SHALL give its select every option and option group the product gives it, in the order given, as that select's own items, read, drawn and chosen by the select (SEL-17, SEL-31 to SEL-45); and SHALL emit its select's events as its own, each once. It SHALL draw no part of its own, hold no state 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 select do when a product places the one in the other (FLD-1 to FLD-28; SEL-1 to SEL-64) — 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, SEL-15, SEL-7); the supporting row and the error, started where the value starts (FLD-7 to FLD-9, FLD-26); the rows drawn focused while the list is open (FLD-13, SEL-20); the name, the description and the states (FLD-10, FLD-11, FLD-14, SEL-11); and the width, which is the Field's and which the select fills (FLD-1, SEL-49).
- **SEF-2** WHERE the platform has forms (the web) THE select field SHALL be the one control the form sees: it SHALL take name, submit its select's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its select would report there (SEL-11), be submitted WHILE readOnly is true (SEL-47), and be left out WHILE disabled is true or a disabled group of the form holds it (SEL-46); its select and its Field SHALL take no part in the form themselves.
- **SEF-3** WHEN the select field is given focus — by the product, by a press on its label row (FLD-12), or by a form that reports its validity — THE select field SHALL pass the focus to its select's container and SHALL add no stop to the focus order: the one stop inside it is its select's (SEL-13). WHILE focus is anywhere inside it, or its select's list is open, THE select field SHALL count as focused for its Field (FLD-13).
- **SEF-4** IF the select field is placed in a Field THE select field SHALL in debug builds report that it is a field already and that the bare control is the select, and both SHALL still render (FLD-15). WHILE it stands in a field group THE select field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
- **SEF-5** THE select field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), emptyText by its select (SEL-62), each from the instance's prop and then from the product's words.
- **SEF-6** 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 select 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 select field is invalid — except those the select 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 (SEF-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 select field SHALL take it off that element. WHEN the product sets an aria- attribute the select field owns THE select 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

- El shadow root del elemento contiene un `<tanrei-field>` con un `<tanrei-select>` dentro, y nada más. Importar el elemento define los dos.
- Las opciones siguen siendo tus hijos de `<tanrei-select-field>`. Nunca se mueven ni se copian: llegan al select de dentro a través de un slot, y el select las vuelve a leer cuando cambian. Sustituirlas a mano (`replaceChildren()`) funciona como en un select.
- El elemento está asociado a formularios. Recibe `name` y `form`, envía solo el valor (nada mientras está deshabilitado, y lo sigue enviando mientras es de solo lectura), se restablece al valor del atributo `value`, sigue a un `<fieldset>` deshabilitado y notifica que falta un valor mientras `required` está activado y el valor está vacío. Sus dos miembros no añaden ninguna entrada al formulario.
- `change` es el evento del select, compuesto y que se propaga. `toggle` es el CustomEvent del select, con `detail.open` y `detail.reason`: es compuesto y no se propaga, de modo que se oye en el elemento y nunca en un ancestro como un `<details>`. El destino de los dos es el elemento, y `event.target.value` y `event.target.open` son los nuevos en todos los listeners.
- Partes: `field` y `select` son los dos miembros. Sus propias partes tienen aquí los mismos nombres que un nivel más abajo: `label-icon`, `supporting-text`; `container`, `outline`, `active-indicator`, `value`, `placeholder`, `leading-icon`, `chevron`, `list`, `option`, `option-label`, `option-supporting-text`, `option-leading-icon`, `mark`, `group`, `group-title`, `divider`, `status`. `label` y `requirement-label` son la que se dibuja de las dos (la fila del campo, o la etiqueta flotante del select), y `field-label`, `select-label`, `field-requirement-label` y `select-requirement-label` nombran la de un solo miembro.
- El elemento no puede recibir el foco por sí mismo: `focus()` va al activador, y un `<label for>` propio de la página lleva el foco allí. Una pulsación en la fila de etiqueta da el foco al activador y no abre nada; una pulsación en el activador abre la lista; una pulsación en la ayuda no hace nada.
- El elemento no tiene rol. Dale nombre con `label` —con `label-hidden` donde la etiqueta se dibuja en otro lugar— y nunca con `aria-label`, que aquí no nombra nada.
- Los atributos son los de los propios miembros: `label-hidden`, `supporting-text`, `error-text`, `required-mark`, `required-text`, `optional-text`, `readonly`.
- Un hijo que no es una opción, ni un grupo de opciones, ni un glifo para `label-icon` o `leading-icon` no se dibuja; una compilación de depuración lo dice.
- Antes de que el elemento esté definido, sus opciones son texto corrido. Oculta `tanrei-select-field:not(:defined) > *` y reserva la altura. Una página que deba funcionar sin script usa un `<select>` nativo con su propio `<label>`.

## Pautas

### Recomendado

- Escribe una etiqueta que nombre lo que se elige, y mantenla visible en un formulario.
- Ordena las opciones como las buscan las personas: por orden alfabético, por número o con las más habituales primero.
- Agrupa una lista larga y da a cada grupo un título corto.
- Preselecciona un valor solo donde la mayoría de las personas lo elegiría.
- Da al campo un ancho con el lugar que ocupa: una columna de un formulario. La caja lo llena.

### Evita

- No uses un campo de selección con `labelHidden` en una barra o en una barra de herramientas. Eso es el [select](https://tanrei.chnotchy.com/es/components/select/) sin nada más, con su propio `label` como nombre.
- No uses el marcador de posición como etiqueta. Desaparece en cuanto se elige algo.
- No navegues, envíes ni elimines en `change` sin decirlo. Las personas recorren una lista para leerla.
- No pongas un campo de selección dentro de un campo. Ya es un campo; una compilación de depuración lo dice. El control que un campo enmarca es el select.
- No le des nombre con `aria-label`. Donde no deba dibujarse ninguna etiqueta, da `label` y `labelHidden`.

## Accesibilidad

### De qué se encarga el componente

- Es un solo cuadro combinado no editable, el del select. Su nombre es `label`, se dibuje o no; su descripción es el texto de apoyo o de error que se muestra, con el texto de opcional mientras el campo es opcional.
- Se expone como no válido mientras `error` es true, como obligatorio mientras `required` está activado, como deshabilitado mientras `disabled` es true, como de solo lectura mientras `readOnly` es true y como expandido mientras su lista está abierta.
- El nombre, la descripción y los estados se vinculan exactamente como un campo los vincula a cualquier control que enmarca. El campo escrito a mano, un nivel más abajo, es el mismo control.
- La etiqueta dibujada, la marca de obligatoriedad y los glifos no se exponen una segunda vez.
- Es una sola parada para la tecla Tab. Una pulsación en la etiqueta lleva el foco al activador y no abre nada; una pulsación en la ayuda no hace nada.
- Un error que aparece mientras el foco está en el campo de selección lo anuncia una vez, de forma cortés, su miembro campo.
- Todo lo que hay en la lista (la opción activa, los nombres, las descripciones y los estados de las opciones, los grupos) es del select, como en la [página del select](https://tanrei.chnotchy.com/es/components/select/#accesibilidad).
- La dirección, el texto ampliado y los colores forzados los resuelve cada miembro por su cuenta.
- No tiene textos propios. `requiredText` y `optionalText`, si se dejan vacíos, los lee el campo de los textos del producto.

Las carencias conocidas en la web son las de sus miembros: el divisor entre dos grupos no se expone como separador, la escritura compara las etiquetas como lo hace JavaScript, y antes de que el elemento esté definido no se dibuja nada más que las opciones como texto.

### Qué debes hacer tú

- Da un `label` a cada campo de selección, y una etiqueta a cada opción.
- Valida tú el valor, activa `error` y escribe `errorText` de modo que diga cómo corregir la respuesta.
- Da las palabras de la obligatoriedad: `required-text` y `optional-text` en el campo de selección, o una sola vez para todo el producto con `setWords({ requiredText, optionalText })`. Tanrei no incluye ninguna: sin `requiredText`, un asterisco ocupa el lugar del tag, y sin `optionalText` no se dibuja ningún tag y no se dice nada. Consulta [Los textos del producto](https://tanrei.chnotchy.com/es/foundations/words/).
- Mantén únicos los valores de las opciones dentro de un campo de selección.