NumberField

Base UICopy Anchor Link

NumberField is the labeled control for typed numbers with increment and decrement. One public element owns value, bounds, step, format, form name, label, helper, error, and the stepper row. Steppers are fixed secondary IconButtons — not custom children and not a Textfield addon API.

Label, description, and error follow the shared field layout. Drag-on-label scrub is on by default when a label is present; turn it off with labelScrub={false} when accidental scrub would be wrong. stepperPlacement is split (button | input | button) or grouped (both at inline-end). fullWidth grows only the numeric input; fitContent shrink-wraps that input. The Base UI root host is display: contents — wrap NumberField in a Stack when a flex row needs the field to grow.

When to useCopy Anchor Link

• Quantities, amounts, counts, and other numbers with optional steppers
• Form fields that submit a number via name, with min / max / step on the same NumberField
• Textfield-aligned label, helper, and validation

When not to useCopy Anchor Link

• Open single-line text (email, search, city) → Textfield
• A continuous scale where position on a track matters → Slider
• Custom stepper children, public Group / Decrement / Increment parts, or Textfield start/end addons

RelatedCopy Anchor Link

• Textfield — open single-line text; use NumberField when the value is numeric with steppers
• Slider — drag a thumb on a track instead of typing
• Fieldset — shared section legend for several fields
• Stack — grow NumberField in a form row (fullWidth + wrap)

Common examplesCopy Anchor Link

Labeled fieldCopy Anchor Link

A guest count with helper copy and default split steppers is the baseline. Bounds, step, label, and description sit on the same NumberField.

Grouped steppersCopy Anchor Link

stepperPlacement="grouped" puts both steppers at inline-end (physical right in LTR, left in RTL). Use it when the control should read as input-then-cluster.

Label without scrubCopy Anchor Link

Default label scrub lets the user drag the label to change the value. Set labelScrub={false} when that gesture would be surprising — policy and retry limits are a common case.

Invalid helperCopy Anchor Link

While the field is invalid and dirty, error replaces description in the shared helper slot — same pattern as Textfield.

Sibling fieldsCopy Anchor Link

Pair a Textfield with a shrink-wrapped NumberField in a centered parent Stack row.

Ask your agentCopy Anchor Link

Add a Guests number field from 1 to 8 with a short helper about suite occupancy and the default split steppers.