---
title: "数値フィールド"
description: "数値を数値として入力できるようにします。ロケールの書き方で入力するか、キーやボタンで増減でき、範囲の中に保たれ、単位が横に付きます。フォームの完成した 1 つのフィールドで、数値入力欄をフィールドで囲んだものです。"
url: "https://tanrei.chnotchy.com/ja/components/number-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# 数値フィールド

> 数値を数値として入力できるようにします。ロケールの書き方で入力するか、キーやボタンで増減でき、範囲の中に保たれ、単位が横に付きます。フォームの完成した 1 つのフィールドで、数値入力欄をフィールドで囲んだものです。

## 概要

数値フィールドは、プロダクトが数値として読む数に使います。数量、サイズ、パーセント、金額などです。ユーザーは自分のロケールの書き方で入力するか、矢印キーやフィールドの末尾側にある 2 つのボタンで増減します。フィールドは、同じバリアントとサイズのテキストフィールドと同じ見た目と寸法です。

**構成要素**は、[フィールド](https://tanrei.chnotchy.com/ja/components/field/)と[数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/)です。フィールドは枠で、ラベル、必須または任意の印、補足、エラーを受け持ちます。数値入力欄はコントロールで、ボックス、数値、単位、2 つのステッパーを受け持ちます。数値フィールドは自分では何も描かず、自分のトークンも持ちません。数値フィールドのプロパティはどれも 2 つのどちらかのプロパティで、そのまま渡されます。

数値フィールドは、すでにフィールドです。[フィールド](https://tanrei.chnotchy.com/ja/components/field/)の中には入れません。スライダーの横やテーブルのセルのように、ラベルがほかの場所にあるところでは、[数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/)を単独で使います。

置かれた場所の幅いっぱいに広がるブロックで、ボックスもその幅いっぱいになります。自分の幅は持ちません。フィールドを狭くするには、置く場所を狭くします。

Web では `<tanrei-number-field>` です。ほかのプラットフォームはまだ実装していません。

### 使い方

`value` は数値で、フィールドが数値を持たない間は `null` です。値が変わるのは、ユーザーが**確定**したときです。フォーカスがフィールドを離れたとき、Enter を押したとき、増減したときで、キーを打つたびには変わりません。入力している間、テキストはユーザーのものです。拒否も、書き直しも、範囲への丸めも、桁の丸めもしません。その間にテキストが表す数は、`input` が運びます。

**Web**

```html
<form>
  <tanrei-number-field name="quantity" label="数量" value="1" min="1" max="99"
    required required-text="必須" invalid-text="数値を入力してください。"
    increment-label="増やす" decrement-label="減らす"></tanrei-number-field>
</form>

<!-- 単位があり、0.25 刻みで、上限はありません。 -->
<tanrei-number-field id="radius" label="角の半径" value="8" min="0" step="0.25" suffix-text="px"
  increment-label="増やす" decrement-label="減らす"></tanrei-number-field>

<!-- 金額。前に記号、後ろにコード、小数は常に 2 桁です。 -->
<tanrei-number-field label="金額" value="120" prefix-text="$" suffix-text="USD"
  min-fraction-digits="2" max-fraction-digits="2"
  increment-label="増やす" decrement-label="減らす"></tanrei-number-field>

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

  const radius = document.querySelector('#radius');
  // 確定によって値が変わりました。value はすでに新しい値で、数値か null です。
  radius.addEventListener('change', () => save(radius.value));
  // ユーザーが入力または増減しています。テキストが表す数で、範囲にも桁にも丸めていません。数でなければ null です。
  radius.addEventListener('input', (e) => preview(e.detail.value));
  // 数ではないテキストが確定されました。フィールドはテキストを残し、invalidText を表示します。
  // detail.text はそのテキストで、フィールドに与えられていなければ空です。
  radius.addEventListener('entryerror', (e) => console.log(e.detail.reason, e.detail.text));
</script>
```

**React**

```tsx
import { NumberField } from '@tanrei/react';

<NumberField label="角の半径" value={radius} min={0} step={0.25} suffixText="px"
  incrementLabel="増やす" decrementLabel="減らす"
  onChange={(event) => setRadius(event.currentTarget.value)} />
```

### 1 つ下の階層

同じフィールドを 2 つの構成要素から自分で書いても、見た目は同じで、支援技術にとっても、同じ名前、説明、状態を持つ同じスピンボタンになります。

```html
<tanrei-field label="数量" required required-text="必須"
  supporting-text="1 回の注文は 99 個までです。">
  <tanrei-number-input name="quantity" min="1" max="99" invalid-text="数値を入力してください。"
    increment-label="増やす" decrement-label="減らす"></tanrei-number-input>
</tanrei-field>
```

数値フィールドにない並べ方が必要なときに、1 つ下の階層で書きます。

| 必要なもの | 使うもの |
| --- | --- |
| ラベル、ボックス、補足、エラー | 数値フィールド |
| 枠の中、ボックスの横か下に置く自分の要素 | [フィールド](https://tanrei.chnotchy.com/ja/components/field/)に、[数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/)と自分の要素を入れる |
| ボックスだけ。ラベルは別の場所にある（スライダーの横、テーブルのセル、ツールバー） | [数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/)を単独で使い、入力欄の `label` で名前を付ける |

1 つ下の階層で変わるのは、何をどこに指定するかです。`name`、`value`、範囲、単位は数値入力欄に指定し、フォームに加わるコントロールもイベントが届く先も入力欄になります。`label`、`error`、`disabled`、必須の指定はフィールドに指定したままにします。フィールドがコントロールに伝えるので、入力欄の側には指定しません。数値フィールドが行い、フィールドと数値入力欄を自分で書いたものが行わないことはありません。

## 仕様

### フィールド

| パーツ | 内容 |
| --- | --- |
| ラベル | フィールドのもの。コンテナの上（`stacked`）。`filled` と `outlined` では数値入力欄がボックスの中で浮き上がるラベルとして描き、フィールドはラベルの行を描きません。描いても `labelHidden` で隠しても、アクセシブルネームになります |
| 必須・任意の印 | フィールドのもの。ラベルの後ろ。`required` では必須のタグ、アスタリスク、または印なし。`optional` では任意のタグ。浮き上がるラベルにはアスタリスクが付きます |
| 入力欄 | 数値入力欄のもの。テキストとしての数値。編集中はユーザーが入力したもの、それ以外は確定した数値をロケールの書き方で示します。1 行で、収まらない分はスクロールします |
| プレフィックス、サフィックス | 数値入力欄のもの。数値の前後に置く決まったテキスト。通貨記号や単位です。ボックスの一部で、値には含まれません |
| ステッパー | 数値入力欄のもの。末尾側にある 2 つのボタン。1 つ目が減らし、2 つ目が増やします。`steppers` を false にすると付きません |
| 補足テキスト | フィールドのもの。補足の 1 行。フィールドがエラーの間は、エラーテキストがその位置に代わって出ます（デザインシステムが両方を残す場合は、その下に）。`error` が true の間は `errorText`、テキストが数でない間は `invalidText` です。ステッパーがあってもなくても、ボックスのテキストのパディングの位置で始まり、同じ位置で終わります |

3 つのバリアントと、3 つのサイズ `small`（32）、`medium`（40）、`large`（56）は、テキストフィールドのものです。既定のシステムが提供するのは `stacked` だけです。

数値フィールドに自分のトークンはありません。ボックスは[数値入力欄のトークン](https://tanrei.chnotchy.com/ja/components/number-input/#%E4%BB%95%E6%A7%98)を、行は[フィールドのトークン](https://tanrei.chnotchy.com/ja/components/field/#%E4%BB%95%E6%A7%98)を、2 つのステッパーは[ボタンのトークン](https://tanrei.chnotchy.com/ja/components/button/#%E4%BB%95%E6%A7%98)を、どこで設定されていても読みます。1 つのインスタンスだけを変えるには、構成要素のトークンをその要素に設定します。`style="--tanrei-comp-field-label-gap: 0.75rem"` のようにします。

2 つのステッパーは、`medium` サイズのテキストボタンで、横に並びます。既定のシステムでは、フィールドの幅のうち 88 を使い、それぞれがタッチターゲットを満たします。小さく描くことも、縦に重ねることもしません。その幅を取れない行では、ステッパーをなくしてください。キーでは引き続き増減できます。

### 値とテキスト

| いつ | 起きること |
| --- | --- |
| ユーザーが入力、貼り付け、音声入力をする | 何も変えません。`input` が、テキストが表す数か `null` を運びます |
| フォーカスが離れる、または Enter | テキストを確定します。`min` まで上げ、`max` まで下げ、`maxFractionDigits` の桁に丸めて値にし、ロケールの書き方で書き戻します。値が変わっていれば `change` を発火します |
| テキストが空 | 値は `null` になります |
| テキストが数ではない | テキストは残ります。値は `null` になり、フィールドはエラーになって `invalidText` を表示し（なければ `errorText`）、`entryerror` を発火します |
| プロダクトが `value` を設定する | 入力されていた内容にかかわらず、その数値を表示します。イベントは発火せず、`min` と `max` による修正もしません |

確定した数値は、ロケールの数字と小数点で、小数部を `minFractionDigits` 桁から `maxFractionDigits` 桁までにして書きます。桁区切りは付けません。表示されているものを、そのまま入力し直せるようにするためです。

テキストは、フィールドの `locale` に従って、寛容に読みます。`locale` が空のときは、ページの言語に従います。

- 数の前後と途中の空白は無視します。
- 数字の前のハイフンマイナス、マイナス記号、プラス記号は、符号として読みます。
- ASCII の数字、ロケールの数字、全角の数字は、どれも数字として読みます。
- 数字の間にあるロケールの桁区切りは無視します。英語では `1,234.50` を 1234.5 と読みます。
- 一緒に入力または貼り付けたプレフィックスとサフィックスは無視します。`12 px` は 12 と読みます。
- 文字、指数、2 つの小数点、符号だけのテキストは、数ではありません。

フィールドは、2 つのロケールの書き方の間で推測しません。小数点がカンマのドイツ語では、`1.500` を 1500、`1.5` を 15 と読みます。

数値とその単位は、ひと続きのテキストです。プレフィックスは数値の前に、サフィックスは数値の後ろに、単位自身の文字の向きで書きます。ページの向きには左右されません。そのため「44 px」「$ 120 USD」「40 %」は、アラビア語やヘブライ語のページでも英語のページと同じ並びになり、アラビア文字やヘブライ文字で書いた単位は数値の左に来ます。ステッパーとラベルはページの向きに従います。`align="end"` は数値を単位の側に寄せます。ラテン文字や記号の単位なら、どちらの向きでも右です。ラテン文字の通貨コードを数値の左に置きたいときは、サフィックスの先頭に右から左への方向マーク（U+200F）を書きます。

### 増減

| 入力 | 起きること |
| --- | --- |
| 上矢印、下矢印 | `step` だけ増減します |
| Page Up、Page Down | `step` の 10 倍だけ増減します |
| ステッパーを押す | 1 回増減します。押し続けると繰り返します。0.5 秒後から 1 秒に 10 回、その後は 1 秒に 20 回です |
| Home、End、左矢印、右矢印 | テキストの中でキャレットを動かします |
| ホイール、ドラッグ | 何も起きません。ページがスクロールします |

増減は、`min` から（なければ 0 から）数えた `step` の目盛りの、次の数に進みます。`step` が 5 なら、12 は上に 15、下に 10 です。計算は 10 進で行うので、0.2 を 0.1 増やすと 0.3 になります。空のフィールドは、範囲が許す中で 0 に最も近い数になります。

`step` は、1 回の増減でどれだけ進むかです。入力できる数は制限しません。`step` が 5 でも、入力した 12 は 12 のままです。特定の数だけを受け付けるには、値を検証して `error` を設定してください。

### スライダーと並べる

1 つの行見出しの下でスライダーの横に置く数値は、ボックスだけです。[数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/#%E3%82%B9%E3%83%A9%E3%82%A4%E3%83%80%E3%83%BC%E3%81%A8%E4%B8%A6%E3%81%B9%E3%82%8B)を単独で使い、入力欄の `label` で名前を付けます。サンプルは数値入力欄のページにあります。

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

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-number-field` | lagging |
| SwiftUI | `TanreiNumberField` | planned |
| Jetpack Compose | `TanreiNumberField` | planned |
| Flutter | `TanreiNumberField` | planned |
| React Native | `NumberField` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `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` |
| `min` (prop) | `min` | `in` | `min` | `min` | `min` |
| `max` (prop) | `max` | `in` | `max` | `max` | `max` |
| `steppers` (prop) | `noSteppers` | `steppers` | `steppers` | `steppers` | `steppers` |
| `incrementLabel` (prop) | `incrementLabel` | `incrementLabel` | `incrementContentDescription` | `incrementSemanticLabel` | `incrementAccessibilityLabel` |
| `decrementLabel` (prop) | `decrementLabel` | `decrementLabel` | `decrementContentDescription` | `decrementSemanticLabel` | `decrementAccessibilityLabel` |
| `prefixText` (prop) | `prefixText` | `prefix` | `prefix` | `prefixText` | `prefix` |
| `suffixText` (prop) | `suffixText` | `suffix` | `suffix` | `suffixText` | `suffix` |
| `valueText` (prop) | `valueText` | `valueText` | `stateDescription` | `semanticValue` | `valueText` |
| `input` (event) | `input` | `onInput` | `onInput` | `onInput` | `onInput` |
| `change` (event) | `change` | `value` | `onValueChange` | `onChanged` | `onValueChange` |
| `action` (event) | `action` | `onSubmit` | `keyboardActions` | `onSubmitted` | `onSubmitEditing` |
| `entryError` (event) | `entryerror` | `onEntryError` | `onEntryError` | `onEntryError` | `onEntryError` |

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 input floats the label it draws no label row.
- `number-input`: The number input, as the Field's one control: the box, the number in it, the prefix and the suffix, the two steppers, 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 number input 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 Number input.) |
| `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 Number input.) |
| `value` | `number` | — | `value` | The committed number, or null (the platform's absent value) while the field holds none. It changes when the person commits — focus leaves, the action key, a step — not on every keystroke; input carries what is being typed. (From Number input.) |
| `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 number input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, NMI-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 input's floating label (FLD-25). Where no message is shown either, the bare number input, named by its own label, is that control without a frame.) |
| `placeholder` | `string` | `""` | `placeholder` | A hint shown while the input is empty and the label is not in the input line. Never a replacement for a name. (From Number input.) |
| `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 number input in the input's own error condition (FLD-8, NMI-10); the steppers stay as they are.) |
| `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 number input, and with it both steppers (FLD-14, NMI-32); the number field is then left out of its form (NUM-48).) |
| `readOnly` | `boolean` | `false` | `readonly` | The number can be focused, selected and copied, but not changed: no key steps it and no stepper is drawn. (From Number input.) |
| `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 number input as required (FLD-10, NMI-12).) |
| `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.) |
| `min` | `number` | — | `min` | The lowest number a commit keeps; a lower one is raised to it. Null for no limit. It is also where the steps are counted from. (From Number input.) |
| `max` | `number` | — | `max` | The highest number a commit keeps; a higher one is lowered to it. Null for no limit. (From Number input.) |
| `step` | `number` | `1` | `step` | How far Up Arrow, Down Arrow and a stepper move the number; Page Up and Page Down move ten times as far. It does not limit what may be typed. (From Number input.) |
| `steppers` | `boolean` | `true` | — | Draws the two stepper buttons at the end of the field. False for a field in a row too narrow for them, or beside a slider that does their work; the keys still step. (From Number input.) |
| `incrementLabel` | `string` | `""` | `increment-label` | The accessible name of the stepper that steps up, in the product's language ("Increase"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. (From Number input.) |
| `decrementLabel` | `string` | `""` | `decrement-label` | The accessible name of the stepper that steps down, in the product's language ("Decrease"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. (From Number input.) |
| `prefixText` | `string` | `""` | `prefix-text` | Fixed text before the number, not part of the value: a currency sign ("$", "¥"). (From Number input.) |
| `suffixText` | `string` | `""` | `suffix-text` | Fixed text after the number, not part of the value: the unit ("px", "ms", "%", "kg"). Read to assistive technology with the number. (From Number input.) |
| `valueText` | `string` | `""` | `value-text` | The value as words ("12 pixels", "3 stars"), given to assistive technology in place of the number with its prefix and suffix. The same text a Slider beside the field takes as its valueText. (From Number input.) |
| `align` | `enum`: `start`, `end` | `"start"` | `align` | Where the number stands in the input: at the start, as the text of every other field, or at the end, for a number in a column of numbers whose digits should line up. (From Number input.) |
| `minFractionDigits` | `number` | `0` | `min-fraction-digits` | The fewest digits shown after the decimal separator; zeros fill them (2 for an amount of money: "12.00"). (From Number input.) |
| `maxFractionDigits` | `number` | `3` | `max-fraction-digits` | The most digits kept after the decimal separator: a commit rounds to it. 0 makes the field hold whole numbers and asks for a keyboard without a separator. (From Number input.) |
| `locale` | `string` | `""` | `locale` | A BCP 47 language tag ("en-US", "de-DE", "ar-EG") for how the number is shown and read: its digits and its decimal separator. Empty uses the platform's current locale. The value itself is a number in every locale. (From Number input.) |
| `invalidText` | `string` | `""` | `invalid-text` | The words for an input committed with a text that is not a number ("Enter a number"): given to the Field that frames it, which shows them as its error text and, while they are empty, shows its own errorText (NMI-21, FLD-28). (From Number input: Shown by the Field, in its supporting row (FLD-28).) |

### Events

| Event | Description |
| --- | --- |
| `input` | The person changed the text, or a step changed the value; carries the number the text reads as — not clamped, not rounded — or the empty value while it reads as none. Emitted for every change, not when the product sets value. What a Slider beside the field follows. (From Number input.) |
| `change` | A commit changed the value: focus left the field, the action key was pressed, a key or a stepper stepped it, or a held stepper was released; carries the value. (From Number input.) |
| `action` | The person pressed the keyboard's action key (Enter, Return, Done). (From Number input.) |
| `entryError` | The person committed a text that is not a number; carries the reason (invalid) and invalidText, the words the input has for it. The entry error itself is shown by the Field that frames the input (NMI-21). (From Number input.) |

### Slots

| Slot | Description |
| --- | --- |
| `label-icon` | A glyph before the label. (From Field.) |

### States

`enabled`, `disabled`, `hovered`, `focused`, `error`

### Accessibility

- Role: `spinbutton`
- Labeling: The number field adds nothing to what its members expose and coordinates nothing: the Field gives the number input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the number input carries them on its own element with its value, its limits and its value text (NMI-12, NMI-34). Assistive technology meets one spin button named by label and two buttons that are no focus stops, exactly as it meets a Field around a number input written by hand.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Every key | The number input's (its accessibility block; NMI-20, NMI-23). The number field handles no key and adds no focus stop (NUM-49). |

- One level down is the same thing: a Field with a number input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (NUM-47).
- On the web the two members stand in the number field's own shadow root, so the form meets the number field and not the input (NUM-48); focus passes through to the input (NUM-49).
- Two levels down, for a number whose label is elsewhere and that shows no message, is the number input alone, named by its own label: beside a slider under one row title, in a table, in a toolbar.

### Behaviour

Requirements in EARS form, each with its stable id.

- **NUM-47** THE number field SHALL be a Field that frames one number input, 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 number input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its number input's events as its own, each once. THE number field SHALL be as wide as the place it stands in, and its number input 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 (NMI-36). 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 number input do when a product places the one in the other (FLD-1 to FLD-28; NMI-1 to NMI-46) — 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, NMI-7, NMI-8); the supporting row and the error (FLD-7 to FLD-9, FLD-26); the name, the description and the states (FLD-10, FLD-11, FLD-14, NMI-12, NMI-32); a text that is not a number shown as an error in the Field's row, in the input's words (FLD-28, NMI-21); and the two steppers, which are the number input's Buttons and stand inside its box (NMI-25).
- **NUM-48** WHERE the platform has forms (the web) THE number field SHALL be the one control the form sees: it SHALL take name, submit its number input's value as that input submits it — a decimal number with ASCII digits and a period, or an empty string WHILE it holds none (NMI-35) — reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its number input would report there (a missing value WHILE required is true and it holds none, NMI-12; a bad input WHILE an entry error lasts, NMI-21), and be left out WHILE disabled is true or a disabled group of the form holds it; its number input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (NMI-20) the form asked SHALL be the number field's own.
- **NUM-49** WHEN the number field is given focus — by the product, by a press on any part of it that FLD-12 or NMI-14 gives to the input, or by a form that reports its validity — THE number field SHALL pass the focus to its number input and SHALL add no stop to the focus order: it has one stop, its input, and the steppers are none (NMI-25). A press on a stepper SHALL step and move no focus, in the number field as in the bare input (NMI-26). WHILE focus is inside it THE number field SHALL count as focused for its Field (FLD-13).
- **NUM-50** IF the number field is placed in a Field THE number field SHALL in debug builds report that it is a field already and that the bare control is the number input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE number field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-14).
- **NUM-51** THE number field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), incrementLabel and decrementLabel by its number input (NMI-44), each from the instance's prop and then from the product's words.
- **NUM-52** 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 number 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 number field is invalid — except those the number field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (NUM-47). 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 number field SHALL take it off that element. WHEN the product sets an aria- attribute the number field owns THE number 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-field>` があり、その中に `<tanrei-number-input>` があります。数値フィールドをインポートすると、どちらも定義されます。
- 数値フィールドは、フォームに関連付けられる要素で、フォームに加わるコントロールはこの要素だけです。`name` を受け取り、ロケールの表示にかかわらず、値を素の 10 進数（`12.5`）として送信します。リセットでは `value` 属性に戻ります。`required` で値がない間は値の欠落を、テキストが数でない間は不正な入力を、フォームに報告します。
- 置かれた場所の幅いっぱいに広がるブロックです。幅を与えない場所では、長いラベルがあるとボックスより広くなります。そこでは幅を与えてください。
- パーツは構成要素のもので、名前も同じです。フィールドからは `label`、`label-icon`、`requirement-label`、`supporting-text`、数値入力欄からは `container`、`outline`、`active-indicator`、`input`、`prefix`、`suffix`、`stepper` です。`label` と `requirement-label` は、2 つのうち描かれているほうに届きます。`field-label` と `number-input-label` は、どちらか一方に届きます。2 つの構成要素は、パーツ `field` と `number-input` です。
- `entryerror` の `detail.text` は入力欄の `invalidText` で、与えられていなければ空です。detail の型は数値入力欄のもので、`TanreiNumberInputInputDetail` と `TanreiNumberInputEntryErrorDetail` です。
- `steppers` は逆の属性 `no-steppers` で、`readOnly` は `readonly` です。
- `input` は `detail.value` を持つ CustomEvent です。`change` と `action` はただのイベントなので、`value` は要素から読みます。`action` をキャンセルしなければ、続けてフォームに送信を求めます。
- `locale` がなければ、最も近い `lang` 属性、次にブラウザーの言語を読みます。
- ロケールの小数点に加えて、桁区切りにピリオドを使わないロケールでは、ピリオドも小数点として読みます。
- ページキーは、スライダーと同じく、`step` の目盛りのまま 10 個分進みます。`step` が 2 なら、42 からの Page Up は 62、次は 82 です。
- iOS と iPadOS では、負の数を入力できる間、フィールドは通常のキーボードを求めます。小数用のキーパッドにマイナス記号がないためです。
- 要素が定義されるまでは、大きさがありません。高さを確保してください。

## ガイドライン

### 数値フィールド、テキストフィールド、スライダー

| 観点 | 数値フィールド | テキストフィールド | スライダー |
| --- | --- | --- | --- |
| 持つもの | 数値 | 任意のテキスト | 範囲の中の数値 |
| 選び方 | 入力または増減 | 入力 | ドラッグ |
| 向いている値 | 分かっている値 | 数量ではない数字 | 感覚で選ぶ値 |

郵便番号、カード番号、電話番号、ワンタイムコードは数字ですが、数量ではありません。郵便番号に 1 を足す人はいません。これらには[テキストフィールド](https://tanrei.chnotchy.com/ja/components/text-field/)を使います。

### 推奨

- 何を数えるのかが分かるラベルを書き、フォームでは見えるようにしておきます。
- 単位は `suffixText` に、通貨記号は `prefixText` に入れます。
- サフィックスがうまく読み上げられない場合は `valueText` を与えます。`×` には「1.5 倍」のようにします。
- `invalidText` には、何を入力すればよいかを書きます。「数値を入力してください。」のようにします。
- 整数には `maxFractionDigits` を 0 にします。キーボードから小数点がなくなります。
- `incrementLabel` と `decrementLabel` を、フィールドに書くか、`setWords()` でプロダクト全体に一度だけ渡します。Tanrei は言葉を同梱しません。名前のないステッパーも描かれ、ポインターでは増減できますが、支援技術からは隠されます。支援技術では、スピンボタン自身が増減するからです。

### 非推奨

- 数量ではない数字に数値フィールドを使わない。
- `input` で保存しない。キーを打つたびに発火します。確定した値は `change` が運びます。
- 利用者側で設定した値を `min` と `max` が修正するとは考えない。適用されるのは、ユーザーが確定したものです。
- 単位を選ぶコントロールをフィールドの中に入れない。[セレクト](https://tanrei.chnotchy.com/ja/components/select/)を横に置きます。
- 数値フィールドをフィールドの中に入れない。すでにフィールドです。フィールドが囲むコントロールは、[数値入力欄](https://tanrei.chnotchy.com/ja/components/number-input/)です。
- 自分のラベルの下にボックスを置くために、数値フィールドのラベルを隠さない。数値入力欄を使います。

## アクセシビリティ

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

- 入力欄はスピンボタンです。名前は `label` で、描いても隠しても同じです。プレースホルダーが名前になることはありません。
- 値は確定した数値で、範囲は `min` と `max` です。
- 表示している補足テキストまたはエラーテキストが説明になります。フィールドが任意の間は `optionalText` も加わります。
- `error` が true の間とテキストが数でない間は invalid、`required` が設定されている間は必須、また読み取り専用として伝えます。
- フィールドにフォーカスがある間に現れたエラーは、1 回、控えめに読み上げます。数ではないテキストのエラーも同じです。
- ステッパーは、`decrementLabel` と `incrementLabel` を名前とするボタンです。名前を与えられていないステッパーは、支援技術から隠します。矢印キーが入力欄から増減するので、フォーカス順には入りません。タッチで探索するユーザーは、ステッパーを見つけられます。
- ステッパーを押してもフォーカスは動かないので、オンスクリーンキーボードは出てきません。
- 入力メソッドが変換している間、フィールドは何も読まず、どのキーも扱いません。
- ホイールが数値を変えることはありません。
- フィールドのヒット領域は最小ターゲットを満たし、それぞれのステッパーもターゲットを満たします。
- テキストを 200% にすると、ラベルと補足は折り返します。数値は 1 行のままで、スクロールします。
- 数値とステッパーが 1 行に並びきらないとき（幅の狭いウィンドウでテキストを 200% にし、プレフィックスと長いサフィックスがあるときなど）は、ステッパーが数値の下の行に移り、ボックスの終わり側に並びます。タッチではステッパーが値を増減する唯一の手段なので、隠れることはありません。
- 強制カラーモードでは、フィールドに縁が付きます。エラーは、言葉と invalid の状態で伝わります。
- 右から左のレイアウトでは、ステッパーとラベルが反転し、ステッパーは左端に来ます。数値とその単位は、単位自身の文字の書き方に従います。ラテン文字や記号の単位は数値の後ろに左から右へ、ページの文字で書いた単位は数値の左に来ます。読み上げられる内容は変わりません。

Web での既知の制約：

- Chromium は、数値を単位なしで読み上げます。値のテキストを入力欄のテキストから取り、フィールドが指定したものを使わないためです。単位が重要な場合は、ラベルに含めてください。
- 要素が定義されるまでは、何も描かれません。

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

- すべての数値フィールドに `label` を与えます。
- `invalidText` はフィールドに書きます。`requiredText`、`optionalText`、`incrementLabel`、`decrementLabel` は、フィールドに書くか、`setWords()` でプロダクト全体に一度だけ渡します。Tanrei は言葉を同梱しません。足りない言葉は開発時に報告されます。[プロダクトの言葉](https://tanrei.chnotchy.com/ja/foundations/words/)を参照してください。
- 値は利用者側で検証して `error` を設定し、`errorText` には数値の直し方を書きます。
- スライダーと、その横の数値入力欄には、同じ名前を与えます。