Number Field

A number field is a numeric input with increment and decrement buttons and an optional scrub area for dragging the value. Use it for bounded, steppable quantities like counts, prices, or percentages, where the value should stay numeric.

Preview

Installation

npx 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
└── NumberFieldGroup
    ├── NumberFieldDecrement
    ├── NumberFieldInput
    ├── NumberFieldIncrement
    ├── NumberFieldStepper
    └── NumberFieldScrubArea
        └── NumberFieldScrubAreaCursor

NumberFieldStepper is an alternative to the separate NumberFieldDecrement / NumberFieldIncrement, stacking both on the right edge.

Examples

Controlled

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

Min / Max

Set min and max on NumberField to constrain the value to a range.

Formatted Display

Pass format (an Intl.NumberFormat options object) to display the value as currency, a percentage, or another number format.

Stacked steppers

Use NumberFieldStepper for a vertically-stacked increment/decrement cluster on the right, the styled equivalent of a native number spinner. The group detects the stepper and caps the input's left edge automatically.

Scrub Area

Wrap a label in NumberFieldScrubArea to let the user drag horizontally to change the value.

Disabled

Set disabled on NumberField to prevent interaction.

Elevated Variant

On a Card, Dialog, or popover surface, the opaque default group collapses into its parent. Use variant="elevated" on NumberFieldGroup for a translucent overlay that adapts to the substrate. See the Surfaces docs.

Variant	Description
`default`	Opaque `bg-input` group for page-level surfaces.
`elevated`	Translucent group for use inside Card, Dialog, or popover.

Form Integration

Use Field for labeling and form participation. See the Forms guide for more patterns.

API Reference

The Number Field component is built on top of Base UI's Number Field. All Base UI props are supported. The documentation below only covers the sub-components available.

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

Sub-components

NumberField

Groups all parts and manages state. Renders a <div> element. Accepts defaultValue, value, onValueChange, min, max, step, format, name, required, disabled, readOnly, and all other Base UI Number Field Root props.

NumberFieldGroup

Groups the input with increment and decrement buttons. Renders a <div> element. The group carries the field's surface (background, shadow, border) so the [-][input][+] cluster reads as a single lifted element.

Prop

Type

Default

NumberFieldInput

The numeric input control. Renders an <input> element. Inherits its surface from NumberFieldGroup, with no variant prop of its own.

NumberFieldIncrement

Button that increases the value when clicked. Renders a <button> element.

NumberFieldDecrement

Button that decreases the value when clicked. Renders a <button> element.

NumberFieldStepper

A vertically-stacked increment (top) and decrement (bottom) cluster for the group's right edge, with built-in chevron icons. Renders a <div> wrapping Base UI's Increment and Decrement. NumberFieldGroup detects it and rounds/borders the input's left edge automatically.

NumberFieldScrubArea

An interactive area where the user can click and drag to change the value. Renders a <span> element.

NumberFieldScrubAreaCursor

A custom cursor element displayed while scrubbing. Renders a <span> element.

On this page