NumberField

A field that only holds a number. The shell is a TextField's, to the pixel; what is added is stepping, clamping and formatting.

import { NumberField } from 'neba';

<NumberField label="Seats" defaultValue={3} min={1} max={20} />;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the surface. A TextField's shell, to the pixel
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale. The steppers are sized in em, so they track the number
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. The surface is white, so it reaches the edge, the ring, the caret and the steppers on hover
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
value	number | null	—	The number. null means empty — never a string you have to parse
defaultValue	number	—	The initial number, for an uncontrolled field
onValueChange	(value: number | null) => void	—	Called on every change — typing, stepping, the wheel
onValueCommitted	(value: number | null) => void	—	Called when the value settles: on blur after typing, on pointer release after a press
min	number	—	The bottom of the range
max	number	—	The top of the range
step	number | 'any'	1	How far one step goes. 'any' turns step validation off
largeStep	number	10	The step taken while Shift is held
smallStep	number	0.1	The step taken while Alt is held
snapOnStep	boolean	false	Whether stepping snaps to multiples of the step
allowWheelScrub	boolean	false	Whether the wheel changes the value while focused and hovered. A page that scrolls under the pointer and a field that changes under it are the same gesture, and only one was meant
format	Intl.NumberFormatOptions	—	How the number is written — currency, percent, decimal places. The field shows $1,240 and still reports 1240
locale	Intl.LocalesArgument	—	Which locale the number is written and parsed in. Defaults to the runtime's
steppers	'end' | 'split' | 'none'	'end'	Where the steppers sit. split puts them on either side of the number; none drops them
label	ReactNode	—	The label, wired to the control by Base UI's Field
description	ReactNode	—	Helper text
error	ReactNode	—	Error message. Its presence turns the control invalid and re-points the colour family at danger
invalid	boolean	!!error	Forces the invalid state without a message, for when a form library owns validity
startIcon	ReactNode	—	Content before the number — a currency mark, a unit
endIcon	ReactNode	—	Content after the number, before the steppers
fullWidth	boolean	false	Stretches to the width of the container
incrementLabel	string	'Increase'	Accessible name of the increment button
decrementLabel	string	'Decrease'	Accessible name of the decrement button
name	string	—	Identifies the field when a form is submitted
readOnly	boolean	false	Shown but not changeable. Keeps its colour and edge, drains the saturation
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey

Not <input type="number">

The native number input rounds the corners off in different places in every browser, ignores the locale, offers a wheel gesture that fights the page's scroll, and hands you a string that is empty when the field holds nonsense. This one keeps the pieces worth keeping and answers each of those:

• value is a number | null, and null means empty. It is never a string you have to parse.
• format is Intl.NumberFormatOptions, so the field shows $1,240 or 7.5% and still reports 1240 and 0.075.
• The arrow keys step by step, Shift by largeStep and Alt by smallStep.
• The wheel does nothing unless allowWheelScrub says otherwise. A page that scrolls under the pointer and a field that changes under it are the same gesture, and only one of them was meant.

Examples

Steppers

import { NumberField } from 'neba';

export default function NumberFieldSteppers() {
  return (
    <div className="flex flex-wrap items-end gap-4">
      <NumberField label="End" steppers="end" defaultValue={2} min={0} />
      <NumberField label="Split" steppers="split" defaultValue={2} min={0} />
      <NumberField label="None" steppers="none" defaultValue={2} min={0} />
    </div>
  );
}

end is the spinner everyone has seen. split puts the minus and the plus on either side of the number, for a quantity that is nudged rather than typed. none drops the buttons and keeps everything else.

There is deliberately no stacked pair of half-height chevrons. At xs each arrow would be under three pixels tall, and a target that small is a target nobody hits.

Formatting

value stays a plain number whatever the field is showing.

import { useState } from 'react';
import { NumberField } from 'neba';

export default function NumberFieldFormat() {
  const [rate, setRate] = useState<number | null>(0.075);

  return (
    <div className="flex flex-col gap-3">
      <div className="flex flex-wrap items-end gap-4">
        <NumberField
          label="Rate"
          value={rate}
          onValueChange={setRate}
          min={0}
          max={1}
          step={0.005}
          format={{ style: 'percent', minimumFractionDigits: 1 }}
        />
        <NumberField
          label="Weight"
          defaultValue={72.5}
          step={0.5}
          format={{ style: 'unit', unit: 'kilogram', unitDisplay: 'short' }}
        />
        <NumberField
          label="Won"
          defaultValue={39000}
          step={1000}
          locale="ko-KR"
          format={{ style: 'currency', currency: 'KRW' }}
        />
      </div>
      <p className="text-xs text-(--neba-muted-fg)">value: {String(rate)}</p>
    </div>
  );
}

Variants

import { NumberField } from 'neba';

export default function NumberFieldVariants() {
  return (
    <div className="flex flex-wrap items-end gap-4">
      <NumberField variant="solid" label="Solid" defaultValue={12} />
      <NumberField variant="outline" label="Outline" defaultValue={12} />
      <NumberField variant="text" label="Text" defaultValue={12} />
    </div>
  );
}

Sizes

The steppers are sized in em, so they track the number rather than carrying a ladder of their own — and the field lines up with a Button, a TextField and a Select of the same size.

import { NumberField } from 'neba';

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

export default function NumberFieldSizes() {
  return (
    <div className="flex flex-wrap items-end gap-3">
      {SIZES.map((size) => (
        <NumberField key={size} size={size} defaultValue={8} min={0} className="w-32" />
      ))}
    </div>
  );
}

States

Read-only takes the steppers away rather than disabling them: a button that is visible and refuses every press is worse than no button. The number stays selectable, because a read-only field is still something you copy out of.

import { NumberField } from 'neba';

export default function NumberFieldStates() {
  return (
    <div className="flex flex-wrap items-start gap-4">
      <NumberField label="Read-only" readOnly defaultValue={4} />
      <NumberField label="Disabled" disabled defaultValue={4} />
      <NumberField label="Seats" min={1} error="At least one seat." defaultValue={0} />
      <NumberField label="Clamped" min={0} max={5} defaultValue={5} description="0 to 5." />
    </div>
  );
}

Accessibility

• Base UI owns the parsing, the clamping, and the press-and-hold repeat on the steppers.
• What you see is a text input carrying inputmode="numeric" and an aria-roledescription of Number field, not <input type="number">. Beside it sits a hidden <input type="number"> holding min, max and step — that is the one a form submits and the browser validates, and keeping the two apart is what lets the visible field show $1,240 without the browser refusing to parse it.
• label becomes the accessible name; the steppers are named by incrementLabel and decrementLabel and stay out of the tab order, because the arrow keys on the field itself already do their job.
• A stepper that has run into min or max is disabled — it changes colour family, the way every other inert control in the library does, rather than fading.