---
title: "Number field"
description: "Lets people enter a number as a number — typed in their locale's form or stepped by a key or a button, kept within limits, with its unit beside it — as one complete field of a form, built from a field and a number input."
url: "https://tanrei.chnotchy.com/components/number-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# Number field

> Lets people enter a number as a number — typed in their locale's form or stepped by a key or a button, kept within limits, with its unit beside it — as one complete field of a form, built from a field and a number input.

## Overview

Use a number field for a number that the product reads as a number: a quantity, a size, a percentage, an amount. People type it in the form of their locale, or step it with the arrow keys or the two buttons at the end of the field. The field is drawn and measured as the text field of the same variant and size.

**Built from** a [field](https://tanrei.chnotchy.com/components/field/) and a [number input](https://tanrei.chnotchy.com/components/number-input/). The field is the frame: the label, the required or optional mark, the help and the error. The number input is the control: the box, the number, its unit and the two steppers. The number field draws nothing of its own and has no token: every property it has is a property of one of the two, given to it unchanged.

A number field is a field already: it is never placed inside a [field](https://tanrei.chnotchy.com/components/field/). Where the label stands elsewhere — beside a slider, in a cell of a table — use the [number input](https://tanrei.chnotchy.com/components/number-input/) alone.

It is a block as wide as the place it is put in, and its box fills it. It has no width of its own: for a narrower field, give it a narrower place.

On the web it is `<tanrei-number-field>`. The other platforms have not implemented it yet.

### Usage

`value` is a number, or `null` while the field holds none. It changes when the person **commits** — focus leaves the field, they press Enter, or they step — and not at every keystroke. While they type, the text is theirs: nothing is refused, reformatted, clamped or rounded. `input` carries what the text reads as meanwhile.

**Web**

```html
<form>
  <tanrei-number-field name="quantity" label="Quantity" value="1" min="1" max="99"
    required required-text="Required" invalid-text="Enter a number." increment-label="Increase" decrement-label="Decrease"></tanrei-number-field>
</form>

<!-- A unit, a step of a quarter, and no upper limit. -->
<tanrei-number-field id="radius" label="Corner radius" value="8" min="0" step="0.25" suffix-text="px" increment-label="Increase" decrement-label="Decrease"></tanrei-number-field>

<!-- Money: a sign before, a code after, always two decimals. -->
<tanrei-number-field label="Amount" value="120" prefix-text="$" suffix-text="USD"
  min-fraction-digits="2" max-fraction-digits="2" increment-label="Increase" decrement-label="Decrease"></tanrei-number-field>

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

  const radius = document.querySelector('#radius');
  // A commit changed the value. It is already the new one: a number, or null.
  radius.addEventListener('change', () => save(radius.value));
  // The person is typing or stepping: the number the text reads as, not clamped and not rounded, or null.
  radius.addEventListener('input', (e) => preview(e.detail.value));
  // A text that is not a number was committed. The field keeps it and shows invalidText:
  // detail.text is that text, empty where the field was given none.
  radius.addEventListener('entryerror', (e) => console.log(e.detail.reason, e.detail.text));
</script>
```

**React**

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

<NumberField label="Corner radius" value={radius} min={0} step={0.25} suffixText="px"
  incrementLabel="Increase" decrementLabel="Decrease"
  onChange={(event) => setRadius(event.currentTarget.value)} />
```

### One level down

The same field, written by hand from its two members, is the same picture, and to assistive technology the same spin button with the same name, description and states:

```html
<tanrei-field label="Quantity" required required-text="Required"
  supporting-text="Up to 99 per order.">
  <tanrei-number-input name="quantity" min="1" max="99" invalid-text="Enter a number."
    increment-label="Increase" decrement-label="Decrease"></tanrei-number-input>
</tanrei-field>
```

Go one level down when you need an arrangement the number field does not offer:

| You need | Use |
| --- | --- |
| A label, the box, help and an error | The number field |
| Something of your own inside the frame, beside or below the box | A [field](https://tanrei.chnotchy.com/components/field/) with a [number input](https://tanrei.chnotchy.com/components/number-input/) and your own element in it |
| The box alone, under a label that stands elsewhere: beside a slider, a cell of a table, a toolbar | The [number input](https://tanrei.chnotchy.com/components/number-input/) alone, named by its own `label` |

What changes one level down is where things are said. `name`, `value`, the limits and the unit are on the number input, which is then the control the form meets, and its events are heard on it. `label`, `error`, `disabled` and the requirement stay on the field, which passes them to the control: do not set the input’s own. There is nothing the number field does that the field and the number input written by hand do not do.

## Specs

### The field

| Part | What it is |
| --- | --- |
| Label | The field’s: above the container (`stacked`). In `filled` and `outlined` the number input draws it, floating inside the box, and the field draws no label row. It is the accessible name, drawn or hidden with `labelHidden` |
| Requirement mark | The field’s, after the label: the requirement tag in its required form, an asterisk or nothing for `required`; the requirement tag in its optional form for `optional`. A floating label takes the asterisk |
| Input | The number input’s: the number as text. What the person typed while they edit; the committed number in the locale’s form otherwise. One line, which scrolls |
| Prefix, suffix | The number input’s: fixed text before and after the number, such as a currency sign or a unit. Part of the box, never of the value |
| Steppers | The number input’s: two buttons at the end, the first steps down, the second up. Leave them out with `steppers` false |
| Supporting text | The field’s: a line of help. While the field is in error the error text takes its place (below it, where the design system keeps both) — `errorText` while `error` is true, and `invalidText` while the text is not a number. It starts and ends at the box’s text padding, with and without steppers |

The three variants and the three sizes, `small` (32), `medium` (40) and `large` (56), are the text field’s. The default system ships `stacked` only.

The number field has no token of its own. Its box reads the [number input’s tokens](https://tanrei.chnotchy.com/components/number-input/#specs), its rows read the [field’s tokens](https://tanrei.chnotchy.com/components/field/#specs), and its two steppers the [Button’s](https://tanrei.chnotchy.com/components/button/#specs), wherever they are set. To change one instance, set a member’s token on it: `style="--tanrei-comp-field-label-gap: 0.75rem"`.

The two steppers are text Buttons of the medium size, side by side. Under the default system they take 88 of the field’s width, and each is a full touch target. They are never drawn smaller and never stacked: where a row cannot afford them, turn them off. The keys still step.

### The value and the text

| When | What happens |
| --- | --- |
| The person types, pastes or dictates | Nothing is changed. `input` carries the number the text reads as, or `null` |
| Focus leaves, or Enter | The text is committed: raised to `min`, lowered to `max`, rounded to `maxFractionDigits`, made the value, and written back in the locale’s form. `change` fires if the value differs |
| The text is empty | The value becomes `null` |
| The text is not a number | The text stays. The value becomes `null`, the field is in error and shows `invalidText` — its `errorText` where there is none — and `entryerror` fires |
| The product sets `value` | The number is shown, whatever was typed. No event fires, and the number is not corrected by `min` and `max` |

A committed number is written with the locale’s digits and decimal separator, between `minFractionDigits` and `maxFractionDigits` digits after it, and without grouping separators — so what is shown can be typed back.

A text is read leniently, by the field’s `locale` — or, where that is empty, by the language of the page:

- Spaces around the number and inside it are ignored.
- A hyphen-minus, a minus sign or a plus sign before the digits is the sign.
- ASCII digits, the locale’s own digits and full-width digits are all digits.
- The locale’s grouping separator is ignored between digits: `1,234.50` reads as 1234.5 in English.
- A typed or pasted prefix and suffix are ignored: `12 px` reads as 12.
- Letters, an exponent, two separators or a sign alone are not a number.

The field never guesses between two locales. In German, where the comma is the decimal separator, `1.500` reads as 1500 and `1.5` as 15.

A number and its unit are one piece of writing. The prefix is written before the number and the suffix after it, in the direction of the unit’s own script, whatever the direction of the page. So “44 px”, “$ 120 USD” and “40 %” read in an Arabic or a Hebrew page as they do in an English one, and a unit written in Arabic or Hebrew letters stands at the number’s left. The steppers and the label follow the page. `align="end"` puts the number against its unit: at the right for a unit in Latin letters or signs, in both directions. For a Latin currency code at the number’s left, begin the suffix with a right-to-left mark (U+200F).

### Stepping

| Input | What happens |
| --- | --- |
| Up Arrow, Down Arrow | Steps by `step` |
| Page Up, Page Down | Steps by ten times `step` |
| A press on a stepper | Steps once. Held, it repeats: after half a second, then ten times a second, then twenty |
| Home, End, Left Arrow, Right Arrow | Move the caret in the text |
| The wheel, a drag | Nothing. The page scrolls |

A step goes to the next number on the step’s grid, counted from `min` (from zero without one): with a step of 5, 12 steps up to 15 and down to 10. It is computed in decimal, so 0.2 stepped by 0.1 is 0.3. An empty field steps to the number nearest to zero that the limits allow.

`step` says how far a step goes. It does not limit what may be typed: with a step of 5, a typed 12 stays 12. To accept only some numbers, validate the value and set `error`.

### With a slider

A number beside a slider, under one row title, is the box alone: a [number input](https://tanrei.chnotchy.com/components/number-input/#with-a-slider), named by its own `label`. Its page has the sample.

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

### What the web draws differently

- The element’s shadow root holds a `<tanrei-field>` with a `<tanrei-number-input>` in it. Importing the number field defines both.
- The number field is a form-associated element, and the one control its form meets. It takes `name` and submits its value as a plain decimal number (`12.5`) whatever the locale shows. It resets to the `value` attribute, and reports a missing value while `required` and it holds none, and a bad input while its text is not a number.
- It is a block as wide as its place. In a place that gives no width, a long label makes it wider than its box: give it a width there.
- Parts are the members’, under their own names: `label`, `label-icon`, `requirement-label` and `supporting-text` from the field; `container`, `outline`, `active-indicator`, `input`, `prefix`, `suffix` and `stepper` from the number input. `label` and `requirement-label` reach whichever of the two is drawn; `field-label` and `number-input-label` reach one. The two members are the parts `field` and `number-input`.
- `entryerror`’s `detail.text` is the input’s `invalidText`, empty where none was given. The detail types are the number input’s: `TanreiNumberInputInputDetail` and `TanreiNumberInputEntryErrorDetail`.
- `steppers` is the inverse attribute `no-steppers`, and `readOnly` is `readonly`.
- `input` is a CustomEvent with `detail.value`. `change` and `action` are plain events: read `value` from the element. Unless `action` is cancelled, the form is then asked to submit.
- Without `locale` the field reads the nearest `lang` attribute, then the browser’s language.
- Besides the locale’s separator, a period is read as the decimal separator wherever the locale does not group with periods.
- A page key steps ten steps on the step’s own grid, as a slider’s does: with a step of 2, Page Up from 42 gives 62, then 82.
- On iOS and iPadOS the field asks for the full keyboard while a negative number may be typed, because the decimal keypad there has no minus sign.
- Before the element is defined it has no size. Reserve the height.

## Guidelines

### Number field, text field or slider

| Aspect | Number field | Text field | Slider |
| --- | --- | --- | --- |
| Holds | A number | Any text | A number within a range |
| Chosen by | Typing or stepping | Typing | Dragging |
| Good for | A value that is known | Digits that are not a quantity | A value chosen by feel |

A postal code, a card number, a telephone number and a one-time code are digits, but not quantities: nobody adds one to a postal code. Use a [text field](https://tanrei.chnotchy.com/components/text-field/) for them.

### Do

- Write a label that names what is counted, and keep it visible in a form.
- Put the unit in `suffixText`, and a currency sign in `prefixText`.
- Give `valueText` where the suffix would be read badly: “1.5 times” for `×`.
- Write `invalidText` so that it says what to type: “Enter a number.”
- Set `maxFractionDigits` to 0 for whole numbers. The keyboard then has no separator.
- Give `incrementLabel` and `decrementLabel`, on the field or once for the whole product with `setWords()`. Tanrei ships no words: a stepper without a name is still drawn and still steps for a pointer, and is kept from assistive technology, where the spin button steps by itself.

### Don’t

- Don’t use a number field for digits that are not a quantity.
- Don’t save on `input`. It fires at every keystroke; `change` carries the committed value.
- Don’t expect `min` and `max` to correct a value you set yourself. They apply to what the person commits.
- Don’t put a control for choosing the unit inside the field. Put a [select](https://tanrei.chnotchy.com/components/select/) beside it.
- Don’t put a number field inside a field. It is a field already; the control a field frames is the [number input](https://tanrei.chnotchy.com/components/number-input/).
- Don’t hide the label of a number field to place the box under a label of your own. Use the number input.

## Accessibility

### What the component handles

- The input is a spin button. Its name is `label`, drawn or hidden, and never the placeholder.
- Its value is the committed number, and its limits are `min` and `max`.
- The shown supporting or error text is its description, with `optionalText` while the field is optional.
- It is exposed as invalid while `error` is true or its text is not a number, as required while `required` is set, and as read-only.
- An error that appears while the field has focus is announced once, politely — a text that is not a number too.
- The steppers are buttons named by `decrementLabel` and `incrementLabel`; one that nobody named is hidden from assistive technology. They are outside the focus order, because the arrow keys step from the input; a person exploring by touch still finds them.
- A press on a stepper does not move focus, so it does not raise the on-screen keyboard.
- While an input method is composing, the field reads nothing and handles no key.
- The wheel never changes the number.
- The field’s hit area meets the minimum target, and each stepper is a full target.
- At 200% text the label and the help wrap. The number stays on one line, and scrolls.
- Where the row cannot hold the number and the steppers side by side — at 200% text in a narrow window, with a prefix and a long suffix — the steppers move to a row of their own below the number, at the box’s end. They are never hidden, because on touch they are the only way to step.
- In forced colors the field gains an edge, and an error is told by its words and the invalid state.
- In a right-to-left layout the steppers and the label are mirrored: the steppers stand at the left end. The number and its unit are written as the unit’s own script writes them: a unit in Latin letters or signs after the number, from left to right, and a unit in the page’s script at the number’s left. What is read aloud does not change.

Known gaps on the web:

- Chromium reads the number without its unit: it takes the value text from the text in the input, and passes over the one the field names. Name the unit in the label where it matters.
- Before the element is defined, nothing is drawn.

### What you need to do

- Give every number field a `label`.
- Write `invalidText` on the field. Give `requiredText`, `optionalText`, `incrementLabel` and `decrementLabel` on the field, or once for the whole product with `setWords()`. Tanrei ships no words; a missing one is reported in development. See [The product’s words](https://tanrei.chnotchy.com/foundations/words/).
- Validate the value yourself, set `error`, and write `errorText` so that it says how to put the number right.
- Give both a slider and the number input beside it the same name.