# InputNumber

## Summary

`InputNumber` collects a single numeric value in a form. Reach for it when the
value benefits from being nudged up or down, such as quantities, prices,
durations, or counts.

Most fields only need the props shown below. For rare layouts the props can't
handle, you can build the same field from smaller pieces. See the **Implement**
tab.

### When to use

* The value is a number the user increments or decrements, like a quantity,
  price, day count, or number of repetitions
* A stepper, min/max bounds, or number formatting would help the user

### When not to use

* The value is a sequence of digits that is never calculated with, such as phone
  numbers, credit-card numbers, or postal codes. A stepper adds no value there;
  use [InputText](../InputText/InputText.md) instead.

## Anatomy

`InputNumber` typically includes:

* Label (required): names the value the field collects
* Value field (required): the number the user types or steps through
* Stepper (optional): increment and decrement controls that change the value by
  `step`
* Prefix or suffix (optional): a unit or symbol shown alongside the value, like
  $ or kg
* Loading indicator (optional): replaces the stepper while background work runs

## Behavior

* The field is controlled through `value`, where a number sets the value and
  `null` leaves it empty.
* `onValueCommitted` fires when the user commits a value: on blur, on Enter, or
  when they use the stepper or arrow keys. Use `onValueChange` for per-keystroke
  updates.
* The stepper buttons and the Up and Down arrow keys change the value by `step`
  (default 1).
* `min` and `max` bound the value, and the stepper stops at each limit.
* `loading` hides the stepper and shows an indicator in its place. The field
  stays editable, so use `readOnly` or `disabled` to lock it.

## Options

### Basic

Pass `label`, a controlled `value`, and `onValueCommitted`. Bounds (`min` /
`max`) and `step` are optional.

```tsx
import React, { useState } from "react";
import type { InputNumberProps } from "@jobber/components";
import { InputNumber } from "@jobber/components";

export function InputNumberBasicExample(props: Partial<InputNumberProps>) {
  const [value, setValue] = useState<number | null>(3);

  return (
    <InputNumber
      label="Quantity"
      min={0}
      max={100}
      {...props}
      value={value}
      onValueCommitted={setValue}
    />
  );
}
```

### Prefixes and suffixes

Use `prefix` or `suffix` to add a unit or symbol. A suffix can be a label, an
icon, or a clickable icon that runs an action (give it an `ariaLabel`).

```tsx
import React, { useState } from "react";
import { InputNumber } from "@jobber/components";
import { Content } from "@jobber/components/Content";

export function InputNumberAffixesExample() {
  const [price, setPrice] = useState<number | null>(42);
  const [days, setDays] = useState<number | null>(7);
  const [reps, setReps] = useState<number | null>(3);

  return (
    <Content>
      <InputNumber
        label="Price"
        prefix={{ label: "$" }}
        suffix={{ label: "USD" }}
        value={price}
        onValueCommitted={setPrice}
      />

      <InputNumber
        label="Follow-up in"
        suffix={{ icon: "calendar", label: "days" }}
        value={days}
        onValueCommitted={setDays}
      />

      <InputNumber
        label="Repetitions"
        suffix={{
          icon: "cross",
          ariaLabel: "Clear value",
          onClick: () => setReps(null),
        }}
        value={reps}
        onValueCommitted={setReps}
      />
    </Content>
  );
}
```

### Sizes

3 sizes are available. `default` fits almost every form; use `small` only in
tight spaces and `large` only in especially spacious layouts.

```tsx
import React, { useState } from "react";
import { InputNumber } from "@jobber/components";
import { Content } from "@jobber/components/Content";

export function InputNumberSizesExample() {
  const [small, setSmall] = useState<number | null>(42);
  const [base, setBase] = useState<number | null>(42);
  const [large, setLarge] = useState<number | null>(42);

  return (
    <Content>
      <InputNumber
        label="Small"
        size="small"
        suffix={{ label: "items" }}
        value={small}
        onValueCommitted={setSmall}
      />
      <InputNumber
        label="Default"
        size="default"
        suffix={{ label: "items" }}
        value={base}
        onValueCommitted={setBase}
      />
      <InputNumber
        label="Large"
        size="large"
        suffix={{ label: "items" }}
        value={large}
        onValueCommitted={setLarge}
      />
    </Content>
  );
}
```

### Formatting

`format` takes any `Intl.NumberFormatOptions` and controls only how the value is
displayed; the committed value stays a plain number. See the **Implement** tab
for how percent and currency values map to the underlying number.

```tsx
import React, { useState } from "react";
import { InputNumber } from "@jobber/components";
import { Content } from "@jobber/components/Content";

export function InputNumberFormattingExample() {
  const [currency, setCurrency] = useState<number | null>(1234.5);
  const [percent, setPercent] = useState<number | null>(0.5);
  const [decimal, setDecimal] = useState<number | null>(11.13);

  return (
    <Content>
      <InputNumber
        label="Currency"
        description='{ style: "currency", currency: "USD" }'
        format={{ style: "currency", currency: "USD" }}
        value={currency}
        onValueCommitted={setCurrency}
      />
      <InputNumber
        label="Percent"
        description='{ style: "percent" } — value is a ratio: 0.5 → 50%'
        format={{ style: "percent", maximumFractionDigits: 2 }}
        value={percent}
        onValueCommitted={setPercent}
      />
      <InputNumber
        label="Decimal"
        description="{ maximumFractionDigits: 2 }"
        format={{ maximumFractionDigits: 2 }}
        value={decimal}
        onValueCommitted={setDecimal}
      />
    </Content>
  );
}
```

### Loading

`loading` shows a non-blocking indicator in the stepper's slot for background
work, like saving. The field stays editable and the stepper is hidden while
loading.

```tsx
import React, { useState } from "react";
import { InputNumber } from "@jobber/components";

export function InputNumberLoadingExample() {
  const [value, setValue] = useState<number | null>(42);

  return (
    <InputNumber
      loading
      label="Quantity"
      suffix={{ label: "items" }}
      value={value}
      onValueCommitted={setValue}
    />
  );
}
```

## Content guidelines

### Label the unit, don't repeat it

Put the unit in the label or an affix, not both.

| ✅ Do                            | ❌ Don't                                 |
| ------------------------------- | --------------------------------------- |
| Label "Weight", suffix "kg"     | Label "Weight (kg)", suffix "kg"        |
| Label "Duration", suffix "days" | Label "Duration in days", suffix "days" |

### Keep labels short and sentence case

| ✅ Do     | ❌ Don't                 |
| -------- | ----------------------- |
| Quantity | Enter the quantity here |
| Discount | DISCOUNT %              |

### Put the symbol where it's read

Use a prefix for a leading symbol and a suffix for a trailing unit, matching how
the value is spoken.

| ✅ Do                 | ❌ Don't              |
| -------------------- | -------------------- |
| Prefix "$", value 40 | Suffix "$", value 40 |
| Suffix "%", value 15 | Prefix "%", value 15 |

### Keep validation errors helpful

When a value breaks `min` or `max`, provide helpful guidance on what values will
be accepted as opposed to just providing a generic error.

| ✅ Do                           | ❌ Don't       |
| ------------------------------ | ------------- |
| Enter a value between 1 and 99 | Invalid input |
| Quantity can't be more than 50 | Error         |

### Use numbers as opposed to spelling them

Use numerals in labels, helper text, affixes, and bounds.

| ✅ Do        | ❌ Don't         |
| ----------- | --------------- |
| Max 3 items | Max three items |

## Do's and Don'ts

#### Do:

* ✅ Use for values the user increments or decrements
* ✅ Set `min` and `max` when the value has real bounds
* ✅ Use `format` for currency, percent, and decimals rather than formatting the
  value yourself
* ✅ Use `loading` for background work so the field stays usable

#### Don't:

* ❌ Use it for digit sequences that are never calculated with, like phone or
  credit card numbers
* ❌ Disable the field to communicate an error; show an `error` message instead
* ❌ Repeat the unit in both the label and an affix

## Accessibility notes

The field is a native number input, so it is reachable and operable by keyboard
and assistive technology.

| Key              | Behavior                        |
| ---------------- | ------------------------------- |
| Tab              | Moves focus to the field        |
| Up / Down arrows | Increment / decrement by `step` |
| Enter            | Commits the current value       |
| Type             | Replaces the value              |

Give a clickable affix a clear `ariaLabel` describing its action, like "Clear
value".

## Related components

* For digit sequences that are not calculated with, like phone or credit card
  numbers, use [InputText](../InputText/InputText.md).
* For dates, use [InputDate](../InputDate/InputDate.md).


## Anatomy

The prop-driven `<InputNumber>` composes a set of parts. You only need these
when the props can't express a layout; otherwise reach for the props shown on
the **Design** tab.

| Part                    | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `Wrapper`               | Owns the field configuration and state; provides it to the parts     |
| `Group`                 | The bordered field row                                               |
| `Input`                 | The input area; holds the `Label` and the `Stepper` / `Loading` slot |
| `Label`                 | Floating field label                                                 |
| `Stepper`               | The increment / decrement button pair                                |
| `Increment` `Decrement` | The individual stepper buttons                                       |
| `Affix`                 | Prefix / suffix content (label, icon, or clickable icon)             |
| `Loading`               | Non-blocking loading indicator slot                                  |
| `Footer`                | Below-field row that holds `Description` and `Error`                 |
| `Description`           | Helper text below the field                                          |
| `Error`                 | Styled error message below the field                                 |

## Composition

The prop-driven component is sugar: it renders exactly the tree you would write
by hand with `<InputNumber.Wrapper>` and the parts. To customize a single piece,
compose the tree yourself and swap that one part — the other parts keep their
defaults. The sugar does not merge consumer-provided parts into its render, so
there is no per-slot precedence to reason about.

`Wrapper` owns the field state and shares it with the parts through context, so
every part must be rendered inside a `Wrapper` (a part used outside one throws).

The example below replaces the default stepper icons with `+` / `−` and leaves
everything else as the default:

```tsx
import React, { useState } from "react";
import { InputNumber } from "@jobber/components";

export function InputNumberCompositionExample() {
  const [value, setValue] = useState<number | null>(3);

  return (
    <InputNumber.Wrapper value={value} onValueCommitted={setValue}>
      <InputNumber.Group>
        <InputNumber.Input>
          <InputNumber.Label>Quantity</InputNumber.Label>
          <InputNumber.Stepper>
            <InputNumber.Increment ariaLabel="Increase Quantity">
              +
            </InputNumber.Increment>
            <InputNumber.Decrement ariaLabel="Decrease Quantity">
              −
            </InputNumber.Decrement>
          </InputNumber.Stepper>
        </InputNumber.Input>
      </InputNumber.Group>
    </InputNumber.Wrapper>
  );
}
```

## Controlled usage

The field is controlled: pass `value` (a `number`, or `null` for empty) and read
changes back through one of two callbacks.

| Callback           | Fires                                                       | Use for                            |
| ------------------ | ----------------------------------------------------------- | ---------------------------------- |
| `onValueChange`    | On every parsed change (typing, paste, stepper, arrow step) | Live-updating UI as the user types |
| `onValueCommitted` | When the user commits (blur, Enter, stepper, arrow step)    | Saving / validating a final value  |

Both emit `null` when the field is empty. Prefer `onValueCommitted` for
persistence so you are not writing on every keystroke.

## Formatting semantics

`format` is forwarded to Base UI's `NumberField` `format` and accepts any
`Intl.NumberFormatOptions`. It changes the display only; the committed value is
always a plain number. Two things to know:

* **Percent** (`{ style: "percent" }`) treats the value as a ratio: `0.5`
  renders `50%`, and the stepper moves in ratio units. If you want the value to
  be the number itself (`50` → `50%`), use `{ style: "unit", unit: "percent" }`.
* With no `format`, typed decimals are preserved (up to 12 fractional digits)
  and thousands grouping follows the locale default, so `1234.5` renders as
  `1,234.5`. Pass `{ useGrouping: false }` to render without separators.


## Props

### Web

#### InputNumber

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `align` | `"center" | "right"` | No | — |  |
| `aria-label` | `string` | No | — |  |
| `aria-labelledby` | `string` | No | — |  |
| `autoComplete` | `InputNumberAutoComplete` | No | — |  |
| `className` | `string` | No | — |  |
| `description` | `ReactNode` | No | — |  |
| `disabled` | `boolean` | No | — |  |
| `error` | `string` | No | — | Renders a styled error message below the field. |
| `format` | `NumberFormatOptions` | No | — | Number formatting for the displayed value, forwarded to Base UI `NumberField`'s native `format`. When omitted, typed ... |
| `id` | `string` | No | — |  |
| `inline` | `boolean` | No | — | Shrink-wrap the field to its content (auto width). |
| `inputMode` | `"decimal" | "numeric"` | No | — | Virtual keyboard hint for mobile. When omitted, Base UI picks the keyboard: `"numeric"` on most platforms, `"decimal"... |
| `invalid` | `boolean` | No | — | Style the error border without showing an error message. |
| `label` | `string` | No | — | Floating field label. |
| `loading` | `boolean` | No | — | Shows a non-blocking loading indicator in the stepper's slot. The field stays editable (use `readOnly`/`disabled` to ... |
| `max` | `number` | No | — |  |
| `min` | `number` | No | — |  |
| `name` | `string` | No | — |  |
| `onBlur` | `(event?: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Also fires once per Enter press: committing on Enter is implemented as a `blur()`/`focus()` round-trip, so `onBlur` a... |
| `onEnter` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — | Fires when Enter is pressed without modifier keys (Shift/Ctrl/Meta). |
| `onFocus` | `(event?: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Also fires once per Enter press; see `onBlur` for the commit mechanics. |
| `onKeyDown` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — |  |
| `onKeyUp` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — |  |
| `onValueChange` | `(newValue: number) => void` | No | — | Fires on every parsed value change (typing, paste, stepper, arrow step). Emits `null` when the field is empty. |
| `onValueCommitted` | `(newValue: number) => void` | No | — | Fires when the user commits a value (blur, Enter, stepper, arrow step). Emits `null` when committed empty. For per-ke... |
| `prefix` | `InputNumberAffix` | No | — |  |
| `readOnly` | `boolean` | No | — |  |
| `ref` | `Ref<InputNumberRef>` | No | — |  |
| `showMiniLabel` | `boolean` | No | — | Default `true`. When `false`, the floating label is hidden. |
| `size` | `InputNumberSize` | No | — |  |
| `step` | `"any" | number` | No | — | Amount the stepper buttons and ArrowUp/ArrowDown keys change the value by. Default `"any"`, which steps by `1` while ... |
| `style` | `CSSProperties` | No | — |  |
| `suffix` | `InputNumberSuffixProp` | No | — |  |
| `value` | `number` | No | — | Controlled value. `number` sets the value; `null` (or `undefined`) is an empty field. |

#### InputNumber.Affix

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variation` | `"prefix" | "suffix"` | Yes | — |  |
| `ariaLabel` | `string` | No | — |  |
| `children` | `ReactNode` | No | — | Arbitrary affix content, beyond the built-in `label`/`icon`. |
| `className` | `string` | No | — |  |
| `icon` | `IconNames` | No | — |  |
| `label` | `string` | No | — |  |
| `onClick` | `() => void` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Decrement

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | No | — | Accessible label for the button. |
| `children` | `ReactNode` | No | — | Icon content. Falls back to the default Atlantis stepper icon. |
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Description

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Error

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `string` | No | — | Error message. Rendered with an alert icon via the `HelperText` primitive. |
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Footer

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Group

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Increment

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | No | — | Accessible label for the button. |
| `children` | `ReactNode` | No | — | Icon content. Falls back to the default Atlantis stepper icon. |
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Input

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | No | — | Content rendered inside the input area (e.g. `.Label`, `.Stepper`). |
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Label

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Loading

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | No | — | Indicator content. Falls back to the default `ActivityIndicator`. |
| `className` | `string` | No | — |  |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Stepper

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | No | — | Stepper buttons. Falls back to the default increment/decrement pair. |
| `className` | `string` | No | — |  |
| `decrementLabel` | `string` | No | — | Accessible label for the decrement button. Defaults to `Decrease value`. |
| `incrementLabel` | `string` | No | — | Accessible label for the increment button. Defaults to `Increase value`. |
| `style` | `CSSProperties` | No | — |  |

#### InputNumber.Wrapper

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `align` | `"center" | "right"` | No | — |  |
| `aria-label` | `string` | No | — |  |
| `aria-labelledby` | `string` | No | — |  |
| `autoComplete` | `InputNumberAutoComplete` | No | — |  |
| `children` | `ReactNode` | No | — | Composed parts (`.Group`, `.Footer`, and the parts within them). |
| `className` | `string` | No | — |  |
| `disabled` | `boolean` | No | — |  |
| `format` | `NumberFormatOptions` | No | — | Number formatting for the displayed value, forwarded to Base UI `NumberField`'s native `format`. When omitted, typed ... |
| `id` | `string` | No | — |  |
| `inline` | `boolean` | No | — | Shrink-wrap the field to its content (auto width). |
| `inputMode` | `"decimal" | "numeric"` | No | — | Virtual keyboard hint for mobile. When omitted, Base UI picks the keyboard: `"numeric"` on most platforms, `"decimal"... |
| `invalid` | `boolean` | No | — | Style the error border without showing an error message. |
| `loading` | `boolean` | No | — | Shows a non-blocking loading indicator in the stepper's slot. The field stays editable (use `readOnly`/`disabled` to ... |
| `max` | `number` | No | — |  |
| `min` | `number` | No | — |  |
| `name` | `string` | No | — |  |
| `onBlur` | `(event?: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Also fires once per Enter press: committing on Enter is implemented as a `blur()`/`focus()` round-trip, so `onBlur` a... |
| `onEnter` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — | Fires when Enter is pressed without modifier keys (Shift/Ctrl/Meta). |
| `onFocus` | `(event?: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Also fires once per Enter press; see `onBlur` for the commit mechanics. |
| `onKeyDown` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — |  |
| `onKeyUp` | `(event: KeyboardEvent<HTMLInputElement>) => void` | No | — |  |
| `onValueChange` | `(newValue: number) => void` | No | — | Fires on every parsed value change (typing, paste, stepper, arrow step). Emits `null` when the field is empty. |
| `onValueCommitted` | `(newValue: number) => void` | No | — | Fires when the user commits a value (blur, Enter, stepper, arrow step). Emits `null` when committed empty. For per-ke... |
| `readOnly` | `boolean` | No | — |  |
| `ref` | `Ref<InputNumberRef>` | No | — |  |
| `showMiniLabel` | `boolean` | No | — | Default `true`. When `false`, the floating label is hidden. |
| `size` | `InputNumberSize` | No | — |  |
| `step` | `"any" | number` | No | — | Amount the stepper buttons and ArrowUp/ArrowDown keys change the value by. Default `"any"`, which steps by `1` while ... |
| `style` | `CSSProperties` | No | — |  |
| `value` | `number` | No | — | Controlled value. `number` sets the value; `null` (or `undefined`) is an empty field. |