NumberField

A numeric input. Looks like a TextField but the bridge value is always number | null — empty string never leaks out, NaN never sneaks in. Optional stepper buttons (+/−) for touch ergonomics; native browser spinner suppressed via CSS so the visual stays clean.

import { NumberField } from '@dashforge/tw';

<NumberField name="age" label="Age" min={0} max={120} />

Quick Start

import { DashForm } from '@dashforge/forms';
import { NumberField, Button } from '@dashforge/tw';

<DashForm onSubmit={onSubmit}>
  <NumberField
    name="quantity"
    label="Quantity"
    min={1}
    max={99}
    step={1}
    showStepper
    required
  />
  <Button type="submit" color="primary">Add to cart</Button>
</DashForm>

Standalone:

const [n, setN] = useState<number | null>(0);
<NumberField name="qty" value={n} onChange={(e) => setN(e.target.valueAsNumber ?? null)} />

Examples

import { NumberField, Stack } from '@dashforge/tw';

<Stack gap={3}>
  <NumberField name="age" label="Age" placeholder="0" />
  <NumberField
    name="quantity"
    label="Quantity"
    defaultValue={1}
    min={1}
    max={99}
    helperText="Between 1 and 99."
  />
</Stack>

With stepper

import { NumberField, Stack } from '@dashforge/tw';

<Stack gap={3}>
  <NumberField
    name="seats"
    label="Seats"
    defaultValue={3}
    min={1}
    max={20}
    showStepper
    helperText="Use the +/− buttons or type a number."
  />
  <NumberField
    name="price"
    label="Price"
    defaultValue={9.99}
    step={0.5}
    min={0}
    showStepper
  />
</Stack>

<NumberField name="qty" min={0} max={10} step={1} showStepper />

Stepper renders +/− buttons inside the field. Tap-friendly on mobile; respects min/max automatically. Hidden by default (showStepper={false}) for desktop-first forms.

Decimals + step

<NumberField name="price" min={0} step={0.01} placeholder="0.00" />
<NumberField name="rating" min={0} max={5} step={0.5} />

step accepts decimals. The bridge value preserves the precision the user typed (no implicit rounding).

Sizes

<NumberField size="sm" name="x" />
<NumberField size="md" name="x" />  {/* default */}
<NumberField size="lg" name="x" />

With validation

<NumberField
  name="age"
  label="Age"
  min={18}
  max={120}
  required
  rules={{
    min: { value: 18, message: 'Must be 18 or over' },
    max: { value: 120, message: 'Must be 120 or under' },
  }}
/>

The min/max props enforce the HTML constraint (native validation, stepper bounds); the rules min/max produce the error message in the helper slot via RHF. Both layers complement each other — use rules when you need a custom message.

Reactive visibility

<Checkbox name="isCompany" label="Buying for a company?" />
<NumberField
  name="employeeCount"
  label="Number of employees"
  visibleWhen={(engine) => engine.getNode('isCompany')?.value === true}
  min={1}
/>

Theme defaults

Configure <NumberField> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    NumberField: {
      defaults: { size: 'md', layout: 'stacked', fullWidth: false },
    },
  },
});

Configurable axes (NumberFieldVariantProps):

Non-visual axes (name, rules, min, max, step, showStepper, label, helperText, error, disabled, access, visibleWhen, event handlers) are not theme-configurable.

Precedence chain (lowest → highest):

1. defaultVariants from the internal numberFieldVariants recipe.
2. theme.components.NumberField.defaults (application-wide).
3. Instance prop (<NumberField size="lg" />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.NumberField.defaults autocompletes to the three axes above; unrecognized fields are compile-time errors.

Reactivity: useComponentDefaults('NumberField') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<NumberField> is a compound component with 9 named slots. Each slot accepts a { className?: string } override via slotProps:

Use sx for a root-level class override, slotProps when you need to reach a specific inner element (e.g. the stepper button color, or the input font weight).

Notes

• Bridge value semantics: the bridge stores number | null. Empty string from the input is normalized to null. NaN from an invalid parse never propagates — the input keeps the user's literal text but the bridge value stays null until valid.
• Native spinner is hidden in CSS (-webkit-appearance: none on the input + MozAppearance: textfield). The optional showStepper renders our own +/− buttons that respect Tailwind theming + min/max.
• For currency: pair with a slotProps.input prefix ($, €, …) or wrap in a custom adornment. We don't ship a <CurrencyField> (yet) — NumberField + step={0.01} covers 90% of cases.
• For percentages: use min={0} max={100} step={1} and render a % suffix via slotProps.input.