Skip to main content
0.24.0
View Zag.js on Github
Join the Discord server

Number Input

The number input provides controls for editing, incrementing or decrementing numeric values using the keyboard or pointer.


Properties

Features

  • Based on the spinbutton pattern.
  • Supports using the scroll wheel to increment and decrement the value.
  • Handles floating point rounding errors when incrementing, decrementing, and snapping to step.
  • Supports pressing and holding the spin buttons to continuously increment or decrement.
  • Supports rounding value to specific number of fraction digits.
  • Support for scrubbing interaction.

Installation

To use the number input machine in your project, run the following command in your command line:

npm install @zag-js/number-input @zag-js/react
# or
yarn add @zag-js/number-input @zag-js/react

This command will install the framework agnostic number input logic and the reactive utilities for your framework of choice.

Anatomy

To set up the number input correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

On a high level, the number input consists of:

  • Root: The root container for the number input.
  • Input: The editable field to change the value.
  • Label: The accessible label for the input.
  • Increment Trigger: The spin button to increment the value.
  • Decrement Trigger: The spin button to decrement the value.
  • Scrubber: The element that allows you to change the value by scrubbing.

Usage

First, import the number input package into your project

import * as numberInput from "@zag-js/number-input"

The number input package exports two key functions:

  • machine — The state machine logic for the number input widget as described in the WAI-ARIA spinner pattern.
  • connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll need to provide a unique id to the useMachine hook. This is used to ensure that the every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the number input machine in your project 🔥

import * as numberInput from "@zag-js/number-input"
import { useMachine, normalizeProps } from "@zag-js/react"

export function NumberInput() {
  const [state, send] = useMachine(numberInput.machine({ id: "1" }))
  
  const api = numberInput.connect(state, send, normalizeProps)

  return (
    <div {...api.rootProps}>
      <label {...api.labelProps}>Enter number:</label>
      <div>
        <button {...api.decrementTriggerProps}>DEC</button>
        <input {...api.inputProps} />
        <button {...api.incrementTriggerProps}>INC</button>
      </div>
    </div>
  )
}

Setting the initial value

To set the initial value of the number input, you can set the value context property.

Note: The value must be a string

const [state, send] = useMachine(
  numberInput.machine({
    value: "13",
  }),
)

Setting a minimum and maximum value

Pass the min prop or max prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range.

const [state, send] = useMachine(
  numberInput.machine({
    min: 10,
    max: 200,
  }),
)

To allow the value overflow the specified min or max, set the allowOverflow: true in the context.

Scrubbing the input value

The number input machine supports the scrubber interaction pattern. The use this pattern, spread the scrubberProps from the api on to the scrubbing element.

It uses the Pointer lock API and tracks the pointer movement. It also renders a virtual cursor which mimicks the real cursor's pointer.

import * as numberInput from "@zag-js/number-input"
import { useMachine, normalizeProps } from "@zag-js/react"

export function NumberInput() {
  const [state, send] = useMachine(numberInput.machine({ id: "1" }))

  const api = numberInput.connect(state, send, normalizeProps)

  return (
    <div {...api.rootProps}>
      <label {...api.labelProps}>Enter number:</label>
      <div>
        <div {...api.scrubberProps} />
        <input {...api.inputProps} />
      </div>
    </div>
  )
}

Using the mousewheel to change value

The number input machine exposes a way to increment/decrement the value using the mouse wheel event. To activate this, pass the allowMouseWheel property to the machine's context.

const [state, send] = useMachine(
  numberInput.machine({
    allowMouseWheel: true,
  }),
)

Clamp value when user blurs the input

In most cases, users can type custom values in the input field. If the typed value is greater than the max, the value is reset to max when the user blur out of the input.

To disable this behavior, pass clampValueOnBlur and set to false.

const [state, send] = useMachine(
  numberInput.machine({
    clampValueOnBlur: false,
  }),
)

Listening for value changes

When the value changes, the onValueChange callback is invoked.

const [state, send] = useMachine(
  numberInput.machine({
    onValueChange(details) {
      // details => { value: string, valueAsNumber: number }
      console.log("value is:", details.value)
    },
  }),
)

Usage within forms

To use the number input within forms, set the name property in the machine's context.

const [state, send] = useMachine(
  numberInput.machine({
    name: "quantity",
  }),
)

Adjusting the precision of the value

To format the input value to be rounded to specific decimal points, set the formatOptions and provide Intl.NumberFormatOptions such as maximumFractionDigits or minimumFractionDigits

const [state, send] = useMachine(
  numberInput.machine({
    formatOptions: {
      maximumFractionDigits: 4,
      minimumFractionDigits: 2,
    },
  }),
)

Format and parse value

To apply custom formatting to the input's value, set the formatOptions and provide Intl.NumberFormatOptions such as style and currency

const [state, send] = useMachine(
  numberInput.machine({
    formatOptions: {
      style: "currency",
      currency: "USD",
    },
  }),
)

Styling guide

Earlier, we mentioned that each number-input's part has a data-part attribute added to them to select and style them in the DOM.

Disabled state

When the number input is disabled, the root, label and input parts will have data-disabled attribute added to them.

The increment and decrement spin buttons are disabled when the number input is disabled and the min/max is reached.

[data-part="root"][data-disabled] {
  /* disabled styles for the input */
}

[data-part="input"][data-disabled] {
  /* disabled styles for the input */
}

[data-part="label"][data-disabled] {
  /* disabled styles for the label */
}

[data-part="increment-trigger"][data-disabled] {
  /* disabled styles for the increment button */
}

[data-part="decrement-trigger"][data-disabled] {
  /* disabled styles for the decrement button */
}

Invalid state

The number input is invalid, either by passing invalid: true or when the value exceeds the max and allowOverflow: true is passed. When this happens, the root, label and input parts will have data-invalid attribute added to them.

[data-part="root"][data-invalid] {
  /* disabled styles for the input */
}

[data-part="input"][data-invalid] {
  /* invalid styles for the input */
}

[data-part="label"][data-invalid] {
  /* invalid styles for the label */
}

Readonly state

When the number input is readonly, the input part will have data-readonly added.

[data-part="input"][data-readonly] {
  /* readonly styles for the input */
}

Increment and decrement spin buttons

The spin buttons can be styled individually with their respective data-part attribute.

[data-part="increment-trigger"] {
  /* styles for the increment trigger element */
}

[data-part="decrement-trigger"] {
  /* styles for the decrement trigger element */
}

Methods and Properties

The number-input's api exposes the following methods:

  • isFocusedbooleanWhether the input is focused.
  • isInvalidbooleanWhether the input is invalid.
  • isValueEmptybooleanWhether the input value is empty.
  • valuestringThe formatted value of the input.
  • valueAsNumbernumberThe value of the input as a number.
  • setValue(value: string | number) => voidFunction to set the value of the input.
  • clearValue() => voidFunction to clear the value of the input.
  • increment() => voidFunction to increment the value of the input by the step.
  • decrement() => voidFunction to decrement the value of the input by the step.
  • setToMax() => voidFunction to set the value of the input to the max.
  • setToMin() => voidFunction to set the value of the input to the min.
  • focus() => voidFunction to focus the input.

Edit this page on GitHub

On this page