Number Field

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

Age

<script setup lang="ts">
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldLabel, NumberFieldRoot } from 'radix-vue'
import { Icon } from '@iconify/vue'
</script>

<template>
  <NumberFieldRoot
    class="text-sm text-white"
    :min="0"
    :default-value="18"
  >
    <NumberFieldLabel>Age</NumberFieldLabel>

    <div class="mt-1 flex items-center border bg-blackA7 border-blackA9 rounded-md">
      <NumberFieldDecrement class="p-2 disabled:opacity-20">
        <Icon icon="radix-icons:minus" />
      </NumberFieldDecrement>
      <NumberFieldInput class="bg-transparent w-20 tabular-nums focus:outline-0 p-1" />
      <NumberFieldIncrement class="p-2 disabled:opacity-20">
        <Icon icon="radix-icons:plus" />
      </NumberFieldIncrement>
    </div>
  </NumberFieldRoot>
</template>

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 component from your command line.

$ npm add radix-vue

Anatomy

Import all parts and piece them together.

<script setup>
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldLabel, NumberFieldRoot } from 'radix-vue'
</script>

<template>
  <NumberFieldRoot>
    <NumberFieldLabel />

    <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 number 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

Label

Label for the input.

Prop	Default	Type
as	'label'	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.

Input

Input

The input component that render the textValue 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 increase 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 decrease 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.

<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 percentage. You need to set the step to 0.01 manually to allow appriopriate step size in this mode.

<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 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.

<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)