---
title: "コンボボックスフィールド"
description: "フォームのフィールドとして、入力して 1 つの値を見つけられるようにします。入力に応じて絞り込まれるオプションのリストが付いたコンボボックスで、そこから選べます。プロダクトが認めていれば、リストにない値も入力できます。フィールドが必須か任意かを伝えられるラベル、1 行の補足、値が違うときの理由が付きます。"
url: "https://tanrei.chnotchy.com/ja/components/combobox-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# コンボボックスフィールド

> フォームのフィールドとして、入力して 1 つの値を見つけられるようにします。入力に応じて絞り込まれるオプションのリストが付いたコンボボックスで、そこから選べます。プロダクトが認めていれば、リストにない値も入力できます。フィールドが必須か任意かを伝えられるラベル、1 行の補足、値が違うときの理由が付きます。

## 概要

コンボボックスフィールドは、フォームが、スクロールして探すより入力したほうが早い 1 つの値を求めるところで使います。数百ある中の都市、人、トークンなどです。フォントファミリーのように、値の候補を示しつつ、リストにない値も受け付けるフィールドにも使えます。ラベル、リストの付いたボックス、1 行の補足、値が違うときの言葉という、いつもの組み合わせが、そのまま使える形でそろっています。ボックスの見た目と寸法は、同じバリアントとサイズのテキストフィールドのボックスと同じで、リストはセレクトのリストと同じように描かれます。

**構成要素**は、[フィールド](https://tanrei.chnotchy.com/ja/components/field/)と[コンボボックス](https://tanrei.chnotchy.com/ja/components/combobox/)です。フィールドは枠で、ラベル、必須または任意の印、補足、エラーを受け持ちます。コンボボックスはコントロールで、ボックス、その中で入力するテキスト、オプションの入ったリストを受け持ちます。コンボボックスフィールドが自分で描くものはなく、トークンもありません。プロパティはどれも 2 つのどちらかのプロパティで、そのまま渡されます。渡したオプションは、コンボボックスのオプションになります。

置かれた場所の幅いっぱいに広がるブロックで、ボックスもその幅いっぱいになります。自分の幅は持ちません。フィールドを狭くするには、置く場所を狭くします。オプションや値に合わせて幅が変わることはありません。ユーザーは、どんなオプションがあるかが分かる前に入力を始めるからです。

Web では、`<tanrei-option>` を子に持つ `<tanrei-combobox-field>` です。子の要素は、[セレクト](https://tanrei.chnotchy.com/ja/components/select/)が持つものと同じです。ほかのプラットフォームはまだ実装していません。

### 使い方

コンボボックスフィールドが持つものは、中のコンボボックスが持つ 2 つのものです。`value` は確定した選択で、選ばれているオプションの値か、リストにないテキストです。`inputValue` は、入力欄にあるテキストです。値が変わるのは、ユーザーがオプションを選んだとき、テキストを確定したとき（アクティブなオプションがないまま Enter を押すか、フィールドを離れたとき）、消去ボタンを押したときだけです。入力したり、リストの中を移動したりしただけで、値が変わることはありません。

**Web**

```html
<form>
  <tanrei-combobox-field name="city" label="都市" value="tokyo" required required-text="必須"
    clearable clear-label="都市を消去" empty-text="一致する項目はありません">
    <tanrei-option value="kyoto">京都</tanrei-option>
    <tanrei-option value="tokyo">東京</tanrei-option>
  </tanrei-combobox-field>
</form>

<!-- ボックスだけ。ラベルが別の場所にあるところでは、自身の label で名前を付けたコンボボックスを使います。コンボボックスフィールドをインポートすると、これも定義されます。 -->
<tanrei-combobox label="トークン" placeholder="トークンを検索" no-chevron style="inline-size: 16rem">
  <tanrei-option value="primary">primary</tanrei-option>
</tanrei-combobox>

<!-- オプションは候補です。どのオプションの名前でもないテキストは、そのまま値になります。 -->
<tanrei-combobox-field label="フォントファミリー" value="Recursive" allow-custom-value>
  <tanrei-option value="Inter">Inter</tanrei-option>
</tanrei-combobox-field>

<!-- 絞り込みは利用者側で行います。input のたびにサーバーに問い合わせ、その状況を状態の行で伝えます。 -->
<tanrei-combobox-field id="assignee" label="担当者" filter="none" no-chevron placeholder="担当者を検索">
  <span slot="leading-icon">person_search</span>
</tanrei-combobox-field>

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

  const assignee = document.querySelector('#assignee');
  // ユーザーがテキストを変えました。コンボボックスはこのイベントを遅らせも間引きもしないので、デバウンスは利用者側で行います。
  assignee.addEventListener('input', async () => {
    assignee.status = 'loading';
    assignee.statusText = '担当者を読み込み中';
    const people = await find(assignee.inputValue);
    assignee.replaceChildren(...people.map(option));
    assignee.status = 'idle';
    assignee.statusText = `${total} 人中 ${people.length} 人を表示`;
  });
  // 確定した値が変わりました。value はすでに新しい値です。
  assignee.addEventListener('change', (e) => save(e.detail.value));
  // ユーザーが開いたか、閉じました。閉じたときは理由が付きます。バブルしないので、フィールドそのものでリッスンします。
  assignee.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
</script>
```

**React**

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

<ComboboxField label="都市" value={city} clearable clearLabel="都市を消去" emptyText="一致する項目はありません" onChange={(event) => setCity(event.detail.value)}>
  <Option value="kyoto">京都</Option>
  <Option value="tokyo">東京</Option>
</ComboboxField>
```

### 1 つ下の階層

コンボボックスフィールドは、[コンボボックス](https://tanrei.chnotchy.com/ja/components/combobox/)を入れた[フィールド](https://tanrei.chnotchy.com/ja/components/field/)です。同じフィールドを 2 つの構成要素から自分で書いても、見た目は同じで、支援技術にとっても、同じ名前、説明、状態を持つ同じコンボボックスになります。ラベルとボックスの間や補足の下に自分の要素を置きたいときなど、コンボボックスフィールドにない並べ方が必要なときに、1 つ下の階層で書きます。

```html
<!-- コンボボックスフィールド -->
<tanrei-combobox-field name="city" label="都市" required required-text="必須"
  supporting-text="注文のお届け先です。" value="tokyo">
  <tanrei-option value="kyoto">京都</tanrei-option>
  <tanrei-option value="tokyo">東京</tanrei-option>
</tanrei-combobox-field>

<!-- 同じものを自分で書いたもの。枠のプロパティはフィールドに、それ以外とオプションはコンボボックスに指定します -->
<tanrei-field label="都市" required required-text="必須" supporting-text="注文のお届け先です。">
  <tanrei-combobox name="city" value="tokyo">
    <tanrei-option value="kyoto">京都</tanrei-option>
    <tanrei-option value="tokyo">東京</tanrei-option>
  </tanrei-combobox>
</tanrei-field>
```

1 つ下の階層で変わるのは、フォームに加わるコントロールがどれかです。自分で書いた場合はコンボボックスで、`name` もコンボボックスに指定します。コンボボックスフィールドでは、フィールドそのものです。

## 仕様

### フィールド

| パーツ | 内容 |
| --- | --- |
| ラベル | コンテナの上のフィールドの行か（`stacked`）、コンテナの中で浮き上がるコンボボックス自身のラベルです（`filled`、`outlined`）。描かれていても、`labelHidden` で隠されていても、アクセシブルネームになります |
| 必須・任意の印 | ラベルの後に置きます。`required` では必須のタグ、アスタリスク、印なしのいずれか、`optional` では任意のタグです。浮き上がるラベルには、アスタリスクが付きます |
| 入力欄 | テキストです。ユーザーがオプションを探すために入力するもので、入力していない間は、選ばれているオプションのラベルか、リストにない値を示します。1 行で、収まらない分はスクロールします |
| プレースホルダー | 入力欄が空の間に表示するヒントです。ラベルの代わりにも、値にもなりません |
| 先頭のアイコン | `leading-icon` スロットのグリフです。なければ、選ばれているオプション自身のグリフになります |
| 消去ボタン | `clearable` を付けると、テキストが空でない間に表示されます。テキストと値を空にします |
| シェブロン | フィールドに見渡せるリストがあることを示し、リストを開閉します。回転はしません。入力した内容に対する候補しかない場合は、付けません（`chevron` を false にします） |
| 補足テキスト | フィールドの行です。補足の 1 行で、`error` が true の間は `errorText` がその位置に代わって出ます（デザインシステムが両方を残す場合は、その下に）。どちらも、入力欄のテキストが始まる位置から始まります |

ラベルの行、印、補足の行は[フィールド](https://tanrei.chnotchy.com/ja/components/field/)のもので、フィールドのトークンで描かれます。それ以外はすべて[コンボボックス](https://tanrei.chnotchy.com/ja/components/combobox/)のものです。3 つのバリアントと、`small`（32）、`medium`（40）、`large`（56）の 3 つのサイズは、テキストフィールドと同じです。既定のシステムが提供するのは `stacked` だけです。

リストが開いている間は、入力欄にフォーカスがあってもなくても、ラベルと補足はボックスと一緒にフォーカスの状態で描かれます。

### リスト

リストは、コンテナの下に、`comp.combobox.list.offset` だけ離れて、コンテナとちょうど同じ幅で開きます。下に余裕がないときは上に開きます。高さは行の高さの合計で、`list.max-height`（320）を超えるとスクロールします。

| パーツ | 内容 |
| --- | --- |
| オプション | ラベルのある行です。補足の 1 行とグリフを添えられます。選ばれているオプションには、控えめな塗りとチェックが付きます |
| 一致した部分 | `filter="contains"` のとき、それぞれのラベルのうち、テキストに一致した部分を太く描きます |
| グループ | ひと続きのオプションで、タイトルを付けられます。絞り込みで空になったグループは描きません |
| 状態の行 | オプションの後に置きます。`statusText` を表示し、`status` が `loading` の間はローディングインジケーターを、`error` の間は失敗したことを、何も一致しなかったときは `emptyText` を表示します |

`filter="contains"` では、ラベルにテキストを含むオプションを表示します。大文字と小文字、全角と半角、文字に付く記号の違いは区別しません。`filter="none"` では、コンボボックスは渡されたオプションをすべて表示し、絞り込みは、`input` を受けて利用者側で行います。コンボボックスが、データの取得、待機、並べ替え、順位付けをすることはありません。

### 入力する、移動する、選ぶ

| 入力 | 起こること |
| --- | --- |
| 文字を入力する | テキストを編集し、絞り込んだリストを開きます。最初に一致したオプションがアクティブになり、入力が止まると読み上げられます。`allowCustomValue` のときは、どれもアクティブになりません |
| リストが閉じているときの下矢印、上矢印。シェブロン | すべてのオプションを表示してリストを開きます。選ばれているオプションが、なければ最初の有効なオプションがアクティブになります |
| リストが開いているときの下矢印、上矢印 | グループをまたいで、次または前のオプションへ移ります。端では一周します（`allowCustomValue` のときはテキストを経由します）。`wrap` が false なら端で止まります |
| Page Down、Page Up | 10 個先または 10 個前のオプションへ移ります |
| Home、End、左矢印、右矢印 | テキストの中でキャレットを動かします |
| オプションがアクティブなときの Enter。オプションを押す | そのオプションを選び、リストを閉じます。フォームは送信しません |
| どのオプションもアクティブでないときの Enter | テキストを確定し、`action` を発火します。`action` がキャンセルされなければ、フォームを送信します |
| Escape | 開いているリストを閉じ、テキストは残します。もう一度押すと、テキストを確定している値のものに戻します。値を消すことはありません |
| Tab、外側を押す | フィールドを離れます。テキストの扱いが決まり、リストが閉じます。アクティブなオプションが選ばれることはありません |
| ラベルを押す | 入力欄にフォーカスを移し、何も開きません。リストが開いている間は、コンボボックスの外側を押したことになります。リストは閉じ、フォーカスは入力欄に残ります |

フィールドを離れると、テキストの扱いが決まります。そのテキストがどの値を表すのかを、コンボボックスが決めるということです。テキストが空なら、値は空になります。テキストがあるオプションのラベル全体と一致していれば、そのオプションが選ばれます。それ以外のテキストは、`allowCustomValue` のときは値になり、そうでなければ破棄されます。

リストは、フォーカスを受けただけでは開きません。そうしたい場合は、利用者側で `open` を設定します。

IME で変換中の間、すべてのキーは IME のものです。変換を確定する Enter で、何かが選ばれたり、送信されたりすることはありません。

`toggle` は、閉じた理由を伝えます。`select`、`commit`、`escape`、`outside`、`press`、`tab`、`focus-out`、`anchor-hidden`、`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`.

### Web での描き方の違い

- `<tanrei-option>` と `<tanrei-option-group>` はデータで、自分では何も描きません。セレクトが持つ要素と同じものです。値が空文字列のオプションは、描かれますが、選べません。空の値は、何も選ばれていないことを表すからです。
- 要素のシャドウルートにあるのは、`<tanrei-combobox>` を入れた `<tanrei-field>` です。子の `<tanrei-option>` は、この要素の子のままで、スロットを通ってコンボボックスに届きます。移動も複製もされません。
- コンボボックスフィールドは、フォームに関連付けられる要素で、フォームから見えるただ 1 つのコントロールです。`name` を受け取り、`value` を送信します。編集しただけで確定していないテキストが送信されることはありません。リセットされると `value` 属性の値に戻ります。`required` で `value` が空の間は、値がないことをフォームに伝えます。どのオプションもアクティブでないときの Enter は、このフィールドのフォームを送信します。
- `value`、`inputValue`、`open` は、どの時点でもコンボボックスのものです。どのリスナーでも、すでに新しい値になっています。
- `chevron` と `wrap` は、逆の意味の属性 `no-chevron` と `no-wrap` で指定します。`readOnly` は、`readonly` 属性です。
- `input` は、テキストの要素のネイティブのイベントです。`change` と `action` は、`detail.value` と `detail.inputValue` を持ちます。4 つのイベントはコンボボックスのもので、イベントのターゲットはコンボボックスフィールドです。`toggle` はバブルしません。
- `focus()` は入力欄に移ります。要素そのものはフォーカスを受け取らず、ロールもありません。名前は `label` で付け、`aria-label` は使いません。
- パーツ: `field` と `combobox` が 2 つの構成要素です。構成要素のパーツは、1 つ下の階層と同じ名前です。`label` と `requirement-label` は、`field-label`、`combobox-label`、`field-requirement-label`、`combobox-requirement-label` としても指定できます。
- 1 つのフィールドだけを変えるには、そのフィールドにカスタムプロパティを設定します。行には `--tanrei-comp-field-*`、ボックスには `--tanrei-comp-input-box-*`、リストには `--tanrei-comp-combobox-*` です。
- リストは、トップレイヤーにある `popover="manual"` の要素です。外側を押すとリストは閉じ、押した位置にある要素にもその操作が届きます。
- 状態の行は、オプションの下に置かれ、オプションと一緒にはスクロールしません。そのため、件数や失敗したことは見えたままになります。
- 要素が定義されるまでの間、オプションはふつうのテキストとして表示されます。`tanrei-combobox-field:not(:defined) > *` を隠し、高さを確保しておいてください。
- Web には固有の戻る操作がないので、`toggle` が理由 `back` を伝えることはありません。

## ガイドライン

### コンボボックスフィールド、セレクト、検索、テキストフィールド

| 観点 | コンボボックスフィールド | セレクト | 検索 | テキストフィールド |
| --- | --- | --- | --- | --- |
| 持つもの | 入力して見つける 1 つの値 | 決まったリストの中の 1 つの値 | 検索語 | 任意のテキスト |
| 選択肢を見せるか | 入力に応じて見せる | 押した後に見せる | 候補と結果を見せる | 見せない |
| リストにない値 | `allowCustomValue` で受け付ける | 受け付けない | 受け付ける | 受け付ける |
| フォームの一部か | はい | はい | いいえ | はい |

1. 短いオプションが 5 つ程度までなら、すべてを見せます。ラジオボタンです。
2. リストがひと目で見渡せる長さで、ほかの値を受け付けないなら、セレクトです。
3. スクロールするより入力したくなるとき、またはリストにない値も受け付けるフィールドなら、コンボボックスフィールドです。
4. 入力した結果が値ではなく行き先になるなら、検索です。
5. 複数の値を選ぶものは、別のコンポーネントです。コンボボックスが持つ値は 1 つです。
6. ラベルが別の場所にあるなら（ツールバーの絞り込み、テーブルのセル）、自身の `label` で名前を付けた、単独の[コンボボックス](https://tanrei.chnotchy.com/ja/components/combobox/)です。

### 推奨

- ラベルには、何を選ぶのかを書き、フォームの中では見える状態にしておきます。
- `allowCustomValue` は、リストにない値が実際に答えになる場合にだけ使います。
- 値がなくてもよいコンボボックスフィールドには `clearable` を付け、`clearLabel` でボタンに名前を付けます。
- オプションを読み込むときは、`status` と `statusText` を設定します。読み込みを待っていること、何件を表示しているか、失敗したことを、リストが伝えられるようになります。
- `emptyText` を、コンボボックスフィールドに書くか、`setWords({ emptyText })` でプロダクト全体に一度だけ渡します。Tanrei は言葉を同梱しません。これがなければ、何にも一致しないテキストに対して行を描かず、リストには表示するものがなくなります。

### 非推奨

- プレースホルダーをラベルの代わりにしない。ユーザーが入力を始めると、すぐに消えます。
- `input` で保存、ページの移動、送信をしない。`input` はキーを押すたびに発火します。確定した値は `change` で受け取ります。
- どのオプションの名前でもないテキストを、フィールドのエラーとして扱わない。そのテキストは、ユーザーがフィールドを離れるときに破棄されます。「リストから選んでください」と伝えたい場合は、利用者側で `error` と `errorText` を設定します。
- コンボボックスフィールドをフィールドの中に入れない。すでにフィールドです。フィールドが囲むコントロールは、[コンボボックス](https://tanrei.chnotchy.com/ja/components/combobox/)です。
- フィールドの多いフォームで、フォーカスを受けたときにリストを開かない。フォーカスが止まるたびに、リストが下のフィールドを覆ってしまいます。

## アクセシビリティ

### コンポーネントが担うこと

- 入力欄は、リストボックスを持つ、編集できるコンボボックスです。名前は `label` で、描かれていても隠されていても変わらず、プレースホルダーが名前になることはありません。フィールドがコンボボックスに渡し、コンボボックスが自身の入力欄に付けます。
- 表示している補足テキストまたはエラーテキストが、説明になります。フィールドが任意の間は、`optionalText` も加わります。
- フィールドの中にフォーカスがある間に現れたエラーは、1 度だけ控えめに読み上げます。
- `error` が true の間は invalid であることを、`required` が設定されている間は必須であることを伝えます。読み取り専用であることと、リストが開いている間は展開されていることも伝えます。
- リストが開いている間も、フォーカスは入力欄にとどまります。アクティブなオプションは、入力欄のアクティブな子孫として伝わります。そのため、文字を入力すれば、いつでもテキストを編集できます。入力でアクティブになったオプションは、入力が 0.5 秒止まってから伝わるので、スクリーンリーダーはまず入力した文字を読み、そのあとで Enter が選ぶオプションを読みます。矢印キーで移動した先のオプションは、すぐに伝わります。
- リストは、ラベルを名前とするリストボックスです。それぞれのオプションは、名前、説明、選ばれているかどうか、無効かどうか、表示されているオプションの中での位置を伝えます。グループの名前は、そのタイトルです。
- 一致した部分は、太さで示します。色だけで示すことはありません。ラベルは、1 つのテキストとして読み上げられます。
- 状態の行は、ライブリージョンです。テキストが変わると控えめに読み上げ、読み込みに失敗したときはすぐに読み上げます。読み込み中は、リストがビジーであることを伝え、何も読み上げません。
- IME で変換中の間、コンボボックスはどのキーも処理しません。
- シェブロンは、ポインターと、タッチで画面を探る操作のためのボタンで、フォーカスの順序には入りません。キーボードでは、下矢印でリストを開きます。
- 消去ボタンは、`clearLabel` を名前とするボタンで、入力欄の次にフォーカスが止まる位置です。
- Escape はリストを閉じ、それより先には届きません。コンボボックスを囲むダイアログは、開いたままです。
- フィールドのヒット領域は、最小ターゲットを満たします。オプションの高さも、最小ターゲット以上です。
- テキストを 200% にすると、ラベル、補足、オプション、タイトル、状態の行は折り返します。1 行のままなのは入力欄のテキストだけで、収まらない分はスクロールします。
- 強制カラーモードでは、フィールドとリストに縁が付き、アクティブなオプションはハイライトの色になります。選ばれているオプションは、チェックで示されます。
- 右から左のレイアウトでは、フィールドとそれぞれの行が左右反転し、それぞれのテキストは自身の方向を保ちます。シェブロン、消去ボタンのグリフ、チェックは反転しません。

Web での既知の制約：

- グループの間の区切り線は、セパレーターとしては伝わりません。リストボックスが持てるのは、オプションとグループだけだからです。
- 絞り込みは、大文字と小文字、全角と半角、文字に付く記号の違いを、どの文字体系でも同じように区別せずに扱います。ハングルを最初の子音で、かなを読みで一致させることはありません。
- 要素が定義されるまでの間、オプションは、コントロールのないテキストとしてページに置かれます。

### 利用者側で行うこと

- すべてのコンボボックスフィールドに `label` を、すべてのオプションにラベルと空でない値を付けます。
- 消去できるコンボボックスフィールドには、`clearLabel` を付けます。
- `statusText` はコンボボックスフィールドに書きます。`emptyText`、`requiredText`、`optionalText`、`clearLabel` は、コンボボックスフィールドに書くか、`setWords()` でプロダクト全体に一度だけ渡します。Tanrei は言葉を同梱しません。足りない言葉は開発時に報告されます。[プロダクトの言葉](https://tanrei.chnotchy.com/ja/foundations/words/)を参照してください。
- 値は利用者側で検証して `error` を設定し、どう直せばよいかが分かる `errorText` を書きます。
- オプションの値は、1 つのコンボボックスフィールドの中で重複させません。