Number Field

A number field holds a value you can type, step with buttons or arrow keys, or drag. Use it for bounded quantities like counts, prices, and percentages.

For a read-only value between buttons, use ButtonGroupText.

Preview#

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Installation#

npxnpx shadcn@latest add @cubby-ui/number-field

Usage#

import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/cubby-ui/number-field";

<NumberField>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>

Composition#

NumberField
├── NumberFieldScrubArea
│   └── NumberFieldScrubAreaCursor
└── NumberFieldGroup
    ├── NumberFieldDecrement
    ├── NumberFieldInput
    ├── NumberFieldIncrement
    ├── NumberFieldStepper
    └── NumberFieldScrubArea

NumberFieldStepper replaces NumberFieldDecrement and NumberFieldIncrement with stacked chevrons on the trailing edge.

Examples#

Controlled#

Use value and onValueChange on NumberField to drive the value yourself.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Min and Max#

Set min and max to keep the value in a range; each stepper turns off at its limit.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Format#

Pass format, an Intl.NumberFormat options object, to show currency, a percentage, or a unit.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Size#

Use size on NumberFieldGroup to match an Input of the same size.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Set [--radius:9999px] on the group for a pill; the steppers' corners follow.

<NumberFieldGroup className="[--radius:9999px]">…</NumberFieldGroup>

Stacked Stepper#

Use NumberFieldStepper for an increment over decrement, like a native number spinner.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Scrub Area#

Wrap a label in NumberFieldScrubArea to change the value by dragging sideways.

"use client";
 
import * as React from "react";
import {
  NumberField,
  NumberFieldDecrement,

Inline Scrub#

Put NumberFieldScrubArea inside the group for a draggable prefix, like a design tool's width field.

import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldScrubArea,
  NumberFieldScrubAreaCursor,

Disabled#

Set disabled on NumberField to turn off typing and stepping.

"use client";
 
import * as React from "react";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  NumberField,

Elevated#

Use variant="elevated" on NumberFieldGroup inside a Card, Dialog, or popover; see Surfaces.

"use client";
 
import * as React from "react";
import {
  Card,
  CardContent,

Form Integration#

Use Field for the label, validation, and form submission; see the Forms guide.

"use client";
 
import { Button } from "@/components/ui/cubby-ui/button";
import { Field, FieldError, FieldLabel } from "@/components/ui/cubby-ui/field";
import { Form } from "@/components/ui/cubby-ui/form";
import {

Accessibility#

Keyboard#

The input is a spinbutton. Arrow keys step by step, Shift+arrow by largeStep, and Alt+arrow by smallStep. Home and End jump to min and max.

Steppers#

The steppers stay out of the tab order, since the arrow keys already step the value. Their labels are "Decrease" and "Increase"; localize them with aria-label, or with incrementProps and decrementProps on NumberFieldStepper.

Labels#

Label the field with Label or FieldLabel. With an inline scrub prefix, give the input its own aria-label, since the prefix is only a symbol.

API Reference#

The Number Field is built on top of Base UI's Number Field. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Number Field documentation.

Props#

NumberFieldGroup#

The shell around the input and steppers. Wraps Base UI's NumberField.Group.

NumberFieldDecrement / NumberFieldIncrement#

Step the value down and up. Wrap Base UI's NumberField.Decrement and NumberField.Increment.

NumberFieldStepper#

Stacked increment and decrement chevrons for the trailing edge. Renders a div around Base UI's NumberField.Increment and NumberField.Decrement; other props go to the div.

NumberFieldScrubAreaCursor#

Replaces the pointer while scrubbing. Wraps Base UI's NumberField.ScrubAreaCursor.

Notes#

NumberFieldInput#

Wraps Base UI's NumberField.Input. The value uses tabular numerals, centered between steppers or left-aligned after an inline scrub prefix. Set the width with className, like className="w-24" for currency.

NumberFieldScrubArea#

Wraps Base UI's NumberField.ScrubArea. Outside the group it wraps a label; inside it, it renders as a quiet prefix.

Upgrading#

If you're reinstalling over an earlier version, check these changes: