---
title: "Number Input"
description: "A number field with decrement and increment buttons that respect min, max and step."
---

Use it when the number itself is what the reader is setting: a slowmode in seconds, a member limit, a retry count. The steppers are real buttons large enough for a finger, and the field between them still takes typing.

What is typed is kept as text until it reads as a number, so the field can be cleared on the way to a new value. A value outside the range is pulled back in when the field is left.

_Live example of Number Input — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add number-input
```

Files written — React: components/ui/number-input.tsx. Vue: components/ui/number-input/NumberInput.vue, components/ui/number-input/index.ts.

## Usage

React:

```tsx
import { NumberInput } from "@/components/ui/number-input"
```

Vue:

```ts
import { NumberInput } from "@/components/ui/number-input"
```

## Examples

### Decimal step

A fractional `step` switches the field to a decimal keyboard. The stepper buttons round the value to the step's precision; a typed value is not rounded unless it has to be corrected to fit the range. `decrementLabel` and `incrementLabel` rename the two buttons for screen readers.

_Live example of Number Input — see the page for the rendered demo._

### Invalid

`min` and `max` already clamp the value, so keep `invalid` for a rule the control cannot know. Raise the limit to 12 to clear the error.

_Live example of Number Input — see the page for the rendered demo._

### Disabled

`disabled` locks the field and both steppers at once, for a value that is shown but set somewhere else.

_Live example of Number Input — see the page for the rendered demo._

## API reference

**`NumberInput`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / v-model` | `number` | — | The current value. In React, leave it undefined and pass `defaultValue` to let the component own it. |
| `onValueChange` | `(value: number) => void` | — | React only. Called whenever the text reads as a number; Vue emits `update:modelValue`. |
| `min` | `number` | — | The lowest value. The decrement button is disabled there. |
| `max` | `number` | — | The highest value. The increment button is disabled there. |
| `step` | `number` | `1` | How far one press moves the value. A fractional step sets how many decimals are kept. |
| `invalid` | `boolean` | `false` | Turns the border to the danger colour and sets `aria-invalid` on the input. |
| `disabled` | `boolean` | `false` | Stops the field and both buttons taking input. |
| `decrementLabel` | `string` | `"Decrease"` | Accessible name of the minus button. |
| `incrementLabel` | `string` | `"Increase"` | Accessible name of the plus button. |

Every other attribute is passed to the number input. `className` (React) or `class` (Vue) lands on the wrapper, which is where a width belongs.

## Accessibility

The field is a native `<input type="number">`, so it is announced as a spin button with its range, and `Up` and `Down` step it without the buttons. The two buttons are named by `decrementLabel` and `incrementLabel`; translate them with the rest of the interface. Name the field itself with a `<label>` or `aria-label`, and say the unit in the label or the helper text, because "15" alone does not say seconds.

`decrementLabel` and `incrementLabel` name the two stepper buttons. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Number Input reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
