Skip to content
v2.5.0
English
Русский
Documentation

NumberField

NumberField is a compound component for numeric entry with optional stepper buttons, bounds, masking, and wheel or keyboard stepping.
StorybookSourceFigma

Overview

NumberField reuses the TextField surface and adds number-specific alignment plus square stepper buttons tied to the shared input height.

Public CSS Variables

VariableValueAffects
keeps controls square with the fieldstepper buttons
No visible change in this state
icon colorstepper buttons
No visible change in this state
hover statestepper buttons
No visible change in this state
active statestepper buttons
No visible change in this state
Button icon color.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state
Button icon color on hover.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state
Button icon color while pressed.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state
Button background.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state
Button background on hover.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state
Button background while pressed.NumberFieldIncrementButton, NumberFieldDecrementButton
No visible change in this state

Edit a value to try it in the demo. Hover a variable to outline what it changes; switch the preview state to see hover, pressed, focus, disabled and invalid variables. Click a name to copy it.

Part-Level Variables

Root

The root adds centered text alignment through .numberTextField.

Buttons

Increment and decrement buttons map --icon-button-size to --input-height.

Input

NumberFieldInput reuses the TextFieldInput contract and adds numeric attributes and centered appearance.

State And Variant Interaction

  • size comes from inherited text-field sizing
  • disabled behavior is derived from root context
  • min/max state typically affects button disabled behavior rather than changing the root surface

Examples

Sizes

size on the root sets --input-height, and the stepper buttons follow it, so they stay square at every size.

stepper-sizes.tsx · 22 lines
import {
  NumberField,
  NumberFieldDecrementButton,
  NumberFieldIncrementButton,
  NumberFieldInput,
} from '@vega-ui/react';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function StepperSizes() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%', maxWidth: 220 }}>

Custom stepper icons

Children of NumberFieldDecrementButton and NumberFieldIncrementButton replace their default icons. Icon-only buttons have no built-in name, so pass aria-label to each.

custom-stepper-icons.tsx · 29 lines
import {
  Icon,
  Label,
  NumberField,
  NumberFieldDecrementButton,
  NumberFieldIncrementButton,
  NumberFieldInput,
} from '@vega-ui/react';
import { ChevronDownIcon, ChevronUpIcon } from '@vega-ui/icons';
import { useId } from 'react';

export default function CustomStepperIcons() {

Do Not Override

  • breaking the square relationship between field height and stepper buttons
  • styling steppers as unrelated icon buttons with mismatched size