Number Field

Alpha

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

View code

Age

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.

$ npm add @internationalized/number

Install the component from your command line.

$ npm add reka-ui

Anatomy

Import all parts and piece them together.

vue

<script setup>
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldRoot } from 'reka-ui'
</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.

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwrite by `asChild`
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`number`
`disabled`		`boolean` When `true`, prevents the user from interacting with the Number Field.
`formatOptions`		`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
`locale`		`string` The locale to use for formatting dates
`max`		`number` The largest value allowed for the input.
`min`		`number` The smallest value allowed for the input.
`modelValue`		`number`
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`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".

Emit	Payload
`update:modelValue`	`[val: number]` Event handler called when the value changes.

Slots (default)	Payload
`modelValue`	`number`
`textValue`	`string`

Data Attribute	Value
`[data-disabled]`	Present when disabled

Input

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

Prop	Default	Type
`as`	`'input'`	`AsTag \| Component` The element or component this component should render as. Can be overwrite by `asChild`
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-disabled]`	Present when disabled

Increment

The button that increases the value.

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwrite by `asChild`
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean`

Data Attribute	Value
`[data-pressed]`	Present when pressed
`[data-disabled]`	Present when disabled

Decrement

The button that decreases the value.

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwrite by `asChild`
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean`

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.

Keyboard Interactions

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

Number Field ​

Features ​

Installation ​

Anatomy ​

API Reference ​

Root ​

Input ​

Increment ​

Decrement ​

Example ​

Decimal ​

Percentage ​

Currency ​

Accessibility ​

Keyboard Interactions ​