# NumberField

A numeric input with increment and decrement buttons.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/NumberField.tsx)

## Overview

NumberField renders a numeric text input with decrement and increment buttons, for quantities adjusted in small steps.

## Examples

### Basic

```tsx
import { NumberField } from '@tempoxyz/ds'

export function Demo() {
  return (
    <NumberField.Root defaultValue={3}>
      <NumberField.Group>
        <NumberField.Decrement />
        <NumberField.Input aria-label="Quantity" />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Basic.tsx)

### Min

Set `min` and `max` on `NumberField.Root` to bound the value.

```tsx
import { NumberField, style } from '@tempoxyz/ds'

export const fill = true
function Example(
  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
    Pick<NumberField.Group.Props, 'invalid'>,
) {
  const { invalid, ...root } = props

  return (
    <NumberField.Root {...root}>
      <NumberField.Group invalid={invalid}>
        <NumberField.Decrement />
        <NumberField.Input aria-label="Quantity" />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Example defaultValue={0} min={0} />
      <Example defaultValue={10} max={10} />
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
    maxWidth: '520px !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Min.tsx)

### Invalid

Set `invalid` on `NumberField.Group` to mark the value as rejected.

```tsx
import { NumberField, style } from '@tempoxyz/ds'

export const fill = true
function Example(
  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
    Pick<NumberField.Group.Props, 'invalid'>,
) {
  const { invalid, ...root } = props

  return (
    <NumberField.Root {...root}>
      <NumberField.Group invalid={invalid}>
        <NumberField.Decrement />
        <NumberField.Input aria-label="Quantity" />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Example defaultValue={5} invalid />
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
    maxWidth: '520px !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Invalid.tsx)

### Disabled

Set `disabled` on `NumberField.Root` to make the field unavailable.

```tsx
import { NumberField, style } from '@tempoxyz/ds'

export const fill = true
function Example(
  props: Pick<NumberField.Root.Props, 'defaultValue' | 'disabled' | 'max' | 'min' | 'step'> &
    Pick<NumberField.Group.Props, 'invalid'>,
) {
  const { invalid, ...root } = props

  return (
    <NumberField.Root {...root}>
      <NumberField.Group invalid={invalid}>
        <NumberField.Decrement />
        <NumberField.Input aria-label="Quantity" />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  )
}

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Example defaultValue={5} disabled />
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr)) !custom',
    maxWidth: '520px !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/NumberField/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { NumberField } from '@tempoxyz/ds'

<NumberField.Root>
  <NumberField.Group>
    <NumberField.Decrement />
    <NumberField.Input />
    <NumberField.Increment />
  </NumberField.Group>
</NumberField.Root>
```

## Guidelines

### When to Use

* Enter a whole number that people nudge up or down, such as webhook retry attempts or block confirmations.
* Set a bounded count, such as seats on a team plan or API keys per project.

### When Not to Use

* Use [AmountInput](/docs/components/amount-input) for token and fiat amounts.
* Use [TextInput](/docs/components/text-input) for codes and identifiers that look numeric, such as a chain ID or a postal code.
* Use [Slider](/docs/components/slider) when an approximate position matters more than the exact number.
* Use [ChoiceGroup](/docs/components/choice-group) or [Select](/docs/components/select) when only a few values are valid, such as 1, 5, or 10 minutes.

### State the Bounds and the Unit

Set `min` and `max`, and state them in `Field.Description`, such as Between 0 and 10. Typed input does not show the range.

Name the unit in the label, such as Timeout (seconds), or add it to the value with `format`. Format large numbers with `format` and `locale`, not hand-written separators.

**Do:** Name the unit in the label and the range in the description.

```tsx
/**
 * Do example for "State the Bounds and the Unit" on the NumberField page.
 * Name the unit in the label and the range in the description.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Block confirmations</Field.Label>
      <NumberField.Root defaultValue={2} max={12} min={1} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
      <Field.Description>Between 1 and 12.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

**Don't:** Leave people to find the bounds by stepping.

```tsx
/**
 * Don't example for "State the Bounds and the Unit" on the NumberField page.
 * Don't leave people to find the bounds by stepping.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Block confirmations</Field.Label>
      <NumberField.Root defaultValue={2} max={12} min={1} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

### Size the Field to the Number

`NumberField.Root` fills its container. Set a `maxWidth` that fits the longest value, so the steppers stay close to the digits.

**Do:** Size the field for a few digits and state the range below it.

```tsx
/**
 * Do example for "Size the Field to the Number" on the NumberField page.
 * Size the field for a few digits and state the range below it.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Retry attempts</Field.Label>
      <NumberField.Root defaultValue={3} max={10} min={0} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
      <Field.Description>Between 0 and 10.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

**Don't:** Stretch a one-digit count across the form.

```tsx
/**
 * Don't example for "Size the Field to the Number" on the NumberField page.
 * Don't stretch a one-digit count across the form.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Retry attempts</Field.Label>
      <NumberField.Root defaultValue={3} max={10} min={0}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Pick Steps People Expect

Set `step` to the increment the value moves in, such as 5 seconds for a timeout. Add `snapOnStep` to snap typed values to a multiple of the step. If a value has no natural step and spans a wide range, typing is faster than stepping.

**Do:** Step a timeout in fives and say so in the description.

```tsx
/**
 * Do example for "Pick Steps People Expect" on the NumberField page.
 * Step a timeout in fives and say so in the description.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Timeout (seconds)</Field.Label>
      <NumberField.Root defaultValue={30} max={60} min={5} step={5} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
      <Field.Description>Between 5 and 60, in steps of 5.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

**Don't:** Step by 1 through a range that people set in fives.

```tsx
/**
 * Don't example for "Pick Steps People Expect" on the NumberField page.
 * Don't step by 1 through a range that people set in fives.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Timeout (seconds)</Field.Label>
      <NumberField.Root defaultValue={31} max={60} min={5} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
      <Field.Description>Between 5 and 60.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

### Avoid Silent Clamping

A typed value outside `min` and `max` is clamped by default, so a typo such as 100 becomes 10.

If a silent change would surprise people, set `allowOutOfRange` and explain the limit in `Field.Error`. Arrow keys and the steppers still clamp.

**Do:** Keep the typed value and explain the limit.

```tsx
/**
 * Do example for "Avoid Silent Clamping" on the NumberField page.
 * Keep the typed value and explain the limit.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Seats</Field.Label>
      <NumberField.Root allowOutOfRange defaultValue={100} max={10} min={1} {...styles.number()}>
        <NumberField.Group invalid>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
      <Field.Error match>Choose up to 10 seats.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

**Don't:** Silently replace a typed 100 with the maximum of 10.

```tsx
/**
 * Don't example for "Avoid Silent Clamping" on the NumberField page.
 * Don't silently replace a typed 100 with the maximum of 10.
 * @module
 */
import { Field, NumberField, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Seats</Field.Label>
      <NumberField.Root defaultValue={10} max={10} min={1} {...styles.number()}>
        <NumberField.Group>
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Group>
      </NumberField.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '8rem !custom' })
}
```

## Accessibility

The keyboard follows the [WAI-ARIA Authoring Practices spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/).

### Semantics

* **NumberField.Group (group):** Groups the input and its steppers.
* **NumberField.Input (textbox):** A text input with a numeric keyboard, announced as a number field.
* **Animated Digits (aria-hidden):** Screen readers skip them and read only the input's value.
* **NumberField.Decrement and NumberField.Increment (button):** Labelled "Decrease" and "Increase". They stay out of the tab order, since arrow keys do the same.
* **Limits (min and max):** A stepper is disabled once the value reaches its limit.
* **Invalid (data-invalid):** `invalid` on the group only fills it red. It sets no ARIA state.

### Keyboard

* **Move Focus to the TextInput (Tab):** Focuses the input but skips the stepper buttons.
* **Step the Value (Up or Down Arrow):** Increases or decreases the value by `step`.
* **Take a Large Step (Shift+Arrow):** Steps by `largeStep`, which defaults to 10.
* **Take a Small Step (Alt+Arrow):** Steps by `smallStep`, which defaults to 0.1.
* **Jump to a Limit (Home or End):** Sets the value to `min` or `max`, when defined.

### Size and Motion

* **Stepper Size (40px):** Steppers sit 4px inside the 48px field, above the 24px WCAG minimum.
* **Reduced Motion (reduce):** If the reader prefers reduced motion, the value morph turns off.

### Your Responsibilities

* **Name the TextInput (aria-label):** Use a field label. Without a visible label, set an `aria-label` such as "Quantity".
* **Mark Invalid Values (aria-invalid):** Set `invalid` on the field, not the group, and explain the problem in an error message.

## Related

[AmountInput](/docs/components/amount-input)

Use for token and fiat amounts.

[TextInput](/docs/components/text-input)

Use for codes and identifiers.

[Slider](/docs/components/slider)

Use for approximate values in a range.

[Field](/docs/components/field)

Use for labels, descriptions, and errors.
