---
title: "Number Field"
description: "A number field allows a user to enter a number and increment or decrement the value using stepper buttons."
canonical_url: "https://vinicunca.dev/akar/components/number-field"
---
# Number Field

> A number field allows a user to enter a number and increment or decrement the value using stepper buttons.

```vue [index.vue]
<script setup lang="ts">
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldRoot } from 'akar'
</script>

<template>
  <div class="akar-demo akar-demo-NumberField">
    <NumberFieldRoot
        id="age"
        class="text-sm text-white"
        :min="0"
        :default-value="18"
      >
        <label for="age">Age</label>
        <div class="mt-1 flex items-center border bg-blackA7 border-blackA9 rounded-md">
          <NumberFieldDecrement class="p-2 disabled:opacity-20">
            <PIcon name="i-lucide-minus" />
          </NumberFieldDecrement>
          <NumberFieldInput class="bg-transparent w-20 tabular-nums focus:outline-0 p-1" />
          <NumberFieldIncrement class="p-2 disabled:opacity-20">
            <PIcon name="i-lucide-plus" />
          </NumberFieldIncrement>
        </div>
      </NumberFieldRoot>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';

@scope (.akar-demo-NumberField) {
/* reset */
button {
  all: unset;
}

.CheckboxRoot {
  background-color: white;
  width: 25px;
  height: 25px;
  border-radius: 4px;
  display: flex;
  align-items: center;
  justify-content: center;
  box-shadow: 0 2px 10px var(--black-a7);
}
.CheckboxRoot:hover {
  background-color: var(--grass-3);
}
.CheckboxRoot:focus {
  box-shadow: 0 0 0 2px black;
}

.CheckboxIndicator {
  color: var(--grass-11);
}
}
```

## Features

- Full keyboard navigation.
- Can be controlled or uncontrolled.
- Support button hold and wheel event.
- Support numbering systems in different locale.
- Customizable formatting.

## Installation

Install the number package.

```bash [pnpm]
pnpm add @internationalized/number
```

```bash [yarn]
yarn add @internationalized/number
```

```bash [npm]
npm install @internationalized/number
```

```bash [bun]
bun add @internationalized/number
```

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<script setup>
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldRoot } from 'akar';
</script>

<template>
  <NumberFieldRoot>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldRoot>
</template>
```

## API Reference

### Root

Contains all the parts of a number field. An `input` will also render when used within a `form` to ensure events propagate correctly.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `defaultValue` |  | `number` |  |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with the Number Field. |
| `disableWheelChange` |  | `boolean` | When `true`, prevents the value from changing on wheel scroll. |
| `focusOnChange` | `true` | `boolean` | When `true`, the input will be focused when the value changes. |
| `formatOptions` |  | `Intl.NumberFormatOptions` | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. |
| `id` |  | `string` | Id of the element |
| `invertWheelChange` |  | `boolean` | When `true`, inverts the direction of the wheel change. |
| `locale` |  | `string` | The locale to use for formatting and currencies |
| `max` |  | `number` | The largest value allowed for the input. |
| `min` |  | `number` | The smallest value allowed for the input. |
| `modelValue` |  | `number \| null` |  |
| `name` |  | `string` | The name of the field. Submitted with its owning form as part of a name/value pair. |
| `readonly` |  | `boolean` | When `true`, the Number Field is read-only. |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `step` | `1` | `number` | The amount that the input value changes with each increment or decrement "tick". |
| `stepSnapping` | `true` | `boolean` | When `false`, prevents the value from snapping to the nearest increment of the step value |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `val: number` |  |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `modelValue` | `number` |  |
| `textValue` | `string` |  |
| `readonly` | `boolean` |  |

[NumberFieldRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/NumberField/NumberFieldRoot.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |

### Input

Input

The input component that renders the text value based on value and format options.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"input"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |

[NumberFieldInput.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/NumberField/NumberFieldInput.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |

### Increment

The button that increases the value.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `disabled` |  | `boolean` |  |

[NumberFieldIncrement.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/NumberField/NumberFieldIncrement.vue)

| Data attribute | Value |
| --- | --- |
| `[data-pressed]` | Present when pressed |
| `[data-disabled]` | Present when disabled |

### Decrement

The button that decreases the value.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `disabled` |  | `boolean` |  |

[NumberFieldDecrement.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/NumberField/NumberFieldDecrement.vue)

| Data attribute | Value |
| --- | --- |
| `[data-pressed]` | Present when pressed |
| `[data-disabled]` | Present when disabled |

## Example

### Decimal

All options supported by `Intl.NumberFormat` are supported, including configuration of minimum and maximum fraction digits, sign display, grouping separators, etc.

```vue
<template>
  <NumberFieldRoot
    :default-value="5"
    :format-options="{
      signDisplay: 'exceptZero',
      minimumFractionDigits: 1,
    }"
  >
    …
  </NumberFieldRoot>
</template>
```

### Percentage

You can set `formatOptions.style` to `percent` to treat the value as a percentage. You need to set the step to 0.01 manually to allow an appropriate step size in this mode.

```vue
<template>
  <NumberFieldRoot
    :default-value="0.05"
    :step="0.01"
    :format-options="{
      style: 'percent',
    }"
  >
    …
  </NumberFieldRoot>
</template>
```

### Currency

You can set `formatOptions.style` to `currency` to treat the value as a currency value. The currency option must also be passed to set the currency code (e.g., USD).

If you need to allow the user to change the currency, you should include a separate dropdown next to the number field. The number field itself will not determine the currency from the user input.

```vue
<template>
  <NumberFieldRoot
    :default-value="5"
    :format-options="{
      style: 'currency',
      currency: 'EUR',
      currencyDisplay: 'code',
      currencySign: 'accounting',
    }"
  >
    …
  </NumberFieldRoot>
</template>
```

## Accessibility

Adheres to the [Spinbutton WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton).

### Keyboard Interactions

| Key | Description |
| --- | --- |
| <kbd>Arrow Up</kbd> | Increase the value |
| <kbd>Arrow Down</kbd> | Decrease the value |
| <kbd>Page Up</kbd> | Increase the value by scale of 10 |
| <kbd>Page Down</kbd> | Decrease the value by scale of 10 |
| <kbd>Home</kbd> | Set value to minimum (if `min` is provided) |
| <kbd>End</kbd> | Set value to maximum (if `max` is provided) |

---

- [ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton)
- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/NumberField)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.