NumberField

Client componentEngine: react-aria

ImportCopy Anchor Link

import { NumberField } from '@nizivo/react/number-field';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/input.css
import '@nizivo/react/css/number-field.css';

Static or interactiveCopy Anchor Link

Client. It is React Aria's NumberField, which reads its Field through FieldScope, so a page with a NumberField also loads FieldScope. The server HTML already shows the value formatted in the locale, and a form submits it before hydration; typing, formatting and stepping work once the page has hydrated. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

PartsCopy Anchor Link

NumberField.Root is the box and holds the value. NumberField.Input is the text input. NumberField.Decrement before it and NumberField.Increment after it add step buttons; leave them out for a price or an amount, where the arrow keys are enough.

Formatting and parsingCopy Anchor Link

formatOptions takes Intl.NumberFormat options: { style: 'currency', currency: 'EUR' }, { style: 'percent' } (0.25 shows as 25 %), { style: 'unit', unit: 'kilogram' }, or fraction digits. The locale is NizivoConfig's locale, en-US without one: in de-DE, "1.234,5" is 1234.5 and shows as "1.234,50 €". The value is formatted on the server too, so the first paint already shows "€12.50".

While the reader types, the text is theirs; on blur or Enter it is parsed, clamped to min and max, snapped to step, and formatted. onValueChange(value, details) reports that committed number, or null when the field is cleared. React Aria reports no cause, so details.reason is 'unknown'.

FormsCopy Anchor Link

With name (or a Field's), a hidden input carries the plain number, 12.5 and never "€12.50", into FormData. Inside a Field, required is checked natively on the visible input, so the Field's messages.valueMissing applies.

Step buttonsCopy Anchor Link

The buttons are out of the tab order, as the arrow keys step the input, and each is disabled at its end of the range. Their names come from React Aria, translated in 36 locales and ending with the field's label: "Decrease Price" and "Increase Price". labels={{ decrement, increment }} replaces them for one field. A child replaces the internal minus or plus mark.

Engine-ownedCopy Anchor Link

The input's role description, "Number field" in English, comes from React Aria's catalogue (it is left out on iOS, where VoiceOver would not announce required with it). labels does not set it, and NizivoConfig's labels do not reach the step buttons: the Strings guide lists the engine-owned strings.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { NumberField } from '@nizivo/react/number-field';

export function NumberFieldExample(): JSX.Element {
  return (
    <Field name="price" label="Price" description="Before tax." required>
      <NumberField.Root
        defaultValue={12.5}
        min={0}
        formatOptions={{ style: 'currency', currency: 'EUR' }}
      >
        <NumberField.Input />
      </NumberField.Root>
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { NumberField } from '@nizivo/react/number-field';

export function NumberFieldPercentExample(): JSX.Element {
  return (
    <Field name="discount" label="Discount">
      <NumberField.Root
        defaultValue={0.15}
        min={0}
        max={1}
        step={0.05}
        formatOptions={{ style: 'percent' }}
      >
        <NumberField.Decrement />
        <NumberField.Input />
        <NumberField.Increment />
      </NumberField.Root>
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { NumberField } from '@nizivo/react/number-field';

export function NumberFieldStatesExample(): JSX.Element {
  return (
    <div style={{ display: 'grid', gap: 16, maxInlineSize: 320 }}>
      <Field label="Weight">
        <NumberField.Root
          defaultValue={1.2}
          formatOptions={{ style: 'unit', unit: 'kilogram', maximumFractionDigits: 2 }}
          size="sm"
        >
          <NumberField.Input />
        </NumberField.Root>
      </Field>
      <Field label="Stock" error="Stock cannot be below the 4 already ordered.">
        <NumberField.Root defaultValue={2} size="lg">
          <NumberField.Decrement />
          <NumberField.Input />
          <NumberField.Increment />
        </NumberField.Root>
      </Field>
      <Field label="Shipping" readOnly>
        <NumberField.Root defaultValue={4.9} formatOptions={{ style: 'currency', currency: 'USD' }}>
          <NumberField.Input />
        </NumberField.Root>
      </Field>
      <Field label="Tax rate" disabled>
        <NumberField.Root defaultValue={0.2} formatOptions={{ style: 'percent' }}>
          <NumberField.Input />
        </NumberField.Root>
      </Field>
    </div>
  );
}

Other exportsCopy Anchor Link

NumberFieldButtonProps type

import type { NumberFieldButtonProps } from '@nizivo/react/number-field'

The props of NumberField.Decrement, listed above.

NumberFieldButtonState type

import type { NumberFieldButtonState } from '@nizivo/react/number-field'

The render state of NumberField.Decrement, listed above.

NumberFieldInputProps type

import type { NumberFieldInputProps } from '@nizivo/react/number-field'

The props of NumberField.Input, listed above.

NumberFieldInputState type

import type { NumberFieldInputState } from '@nizivo/react/number-field'

The render state of NumberField.Input, listed above.

NumberFieldLabels type

import type { NumberFieldLabels } from '@nizivo/react/number-field'

The step buttons' names (§9.3 rule 7). Unset, React Aria renders its own localized names, which include the field's label ("Increase Price"; 36 locales), so they are not in the enUS catalogue and NizivoConfig does not set them.

Name	Type	Default	Description
decrementrequired	string	–	The Decrement button's name.
incrementrequired	string	–	The Increment button's name.

NumberFieldRootProps type

import type { NumberFieldRootProps } from '@nizivo/react/number-field'

The props of NumberField.Root, listed above.

NumberFieldRootState type

import type { NumberFieldRootState } from '@nizivo/react/number-field'

Name	Type	Default	Description
disabledrequired	boolean	–
invalidrequired	boolean	–
readOnlyrequired	boolean	–
requiredrequired	boolean	–

NumberFieldValueReason type

import type { NumberFieldValueReason } from '@nizivo/react/number-field'

React Aria reports no cause for a change.

type NumberFieldValueReason = "unknown"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-input, .nz-number-field, .nz-number-field-button, .nz-number-field-icon, .nz-number-field-input.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• number-field: draws the outline when the field inside it has focus.

Behaviour comes from the react-aria engine through Nizivo's adapter: focus management, ARIA wiring and keyboard handling are the engine's.

KeyboardCopy Anchor Link

Source: React Aria Components 1.22.1 NumberField (_engines/react-aria/number-field.client.tsx). The browser lane (test/browser/number-field.spec.tsx) checks typing and the commit, de-DE parsing, the arrow keys, the step buttons, Tab skipping them, FormData, controlled use and a Field's required message.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none