NumberField

Number input fields with increment/decrement buttons, validation, and internationalized formatting

Usage

1import { NumberField } from '@lenso/ui';

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Label, NumberField, TextField } from "@lenso/ui";5import { Controls, styles } from "./parts";6
7export function Basic() {8  return (9    <TextField name="width" xstyle={styles.field}>10      <NumberField defaultValue={1024} min={0} name="width">11        <Label>Width</Label>12        <Controls />13      </NumberField>14    </TextField>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

1import {NumberField, Label, Description, FieldError} from '@lenso/ui';2
3export default () => (4  <NumberField>5    <Label />6    <NumberField.Group>7      <NumberField.DecrementButton />8      <NumberField.Input />9      <NumberField.IncrementButton />10    </NumberField.Group>11    <Description />12    <FieldError />13  </NumberField>14)

NumberField allows users to enter numeric values with optional increment/decrement buttons. It supports internationalized formatting, validation, and keyboard navigation.

Examples

Variants

The NumberField component supports two visual variants:

primary (default) - Standard styling with shadow, suitable for most use cases
secondary - Lower emphasis variant without shadow, suitable for use in Surface components

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function Variants() {8  return (9    <div {...stylex.props(styles.column)}>10      {(["primary", "secondary"] as const).map((variant) => (11        <TextField key={variant} name={`${variant}-width`}>12          <NumberField defaultValue={100} min={0} name={`${variant}-width`} variant={variant}>13            <Label>{variant === "primary" ? "Primary variant" : "Secondary variant"}</Label>14            <Controls />15          </NumberField>16        </TextField>17      ))}18    </div>19  );20}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, Surface, TextField } from "@lenso/ui";4import { Controls, styles } from "./parts";5
6export function OnSurface() {7  return (8    <Surface xstyle={styles.surface}>9      <TextField name="width">10        <NumberField defaultValue={1024} min={0} name="width" variant="secondary">11          <Label>Width</Label>12          <Controls fullWidth />13          <Description>Enter the width in pixels</Description>14        </NumberField>15      </TextField>16      <TextField name="percentage">17        <NumberField18          defaultValue={0.5}19          format={{ style: "percent" }}20          min={0}21          max={1}22          name="percentage"23          step={0.1}24          variant="secondary"25        >26          <Label>Percentage</Label>27          <Controls fullWidth />28          <Description>Value must be between 0 and 100</Description>29        </NumberField>30      </TextField>31    </Surface>32  );33}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Description

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function WithDescription() {8  return (9    <div {...stylex.props(styles.column)}>10      <TextField name="width">11        <NumberField defaultValue={1024} min={0} name="width">12          <Label>Width</Label>13          <Controls />14          <Description>Enter the width in pixels</Description>15        </NumberField>16      </TextField>17      <TextField name="percentage">18        <NumberField19          defaultValue={0.5}20          format={{ style: "percent" }}21          min={0}22          max={1}23          name="percentage"24          step={0.1}25        >26          <Label>Percentage</Label>27          <Controls />28          <Description>Value must be between 0 and 100</Description>29        </NumberField>30      </TextField>31    </div>32  );33}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Required Field

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function Required() {8  return (9    <div {...stylex.props(styles.column)}>10      <TextField name="quantity">11        <NumberField required min={0} name="quantity">12          <Label required>Quantity</Label>13          <Controls />14        </NumberField>15      </TextField>16      <TextField name="rating">17        <NumberField required defaultValue={1} min={1} max={10} name="rating">18          <Label required>Rating</Label>19          <Controls />20          <Description>Rate from 1 to 10</Description>21        </NumberField>22      </TextField>23    </div>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Disabled State

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function Disabled() {8  return (9    <div {...stylex.props(styles.column)}>10      <TextField disabled name="width">11        <NumberField disabled defaultValue={1024} min={0} name="width">12          <Label>Width</Label>13          <Controls />14          <Description>Enter the width in pixels</Description>15        </NumberField>16      </TextField>17      <TextField disabled name="percentage">18        <NumberField19          disabled20          defaultValue={0.5}21          format={{ style: "percent" }}22          min={0}23          max={1}24          name="percentage"25          step={0.1}26        >27          <Label>Percentage</Label>28          <Controls />29          <Description>Value must be between 0 and 100</Description>30        </NumberField>31      </TextField>32    </div>33  );34}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Full Width

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "./parts";6
7export function FullWidth() {8  return (9    <div {...stylex.props(styles.wide)}>10      <TextField name="width" fullWidth>11        <NumberField fullWidth defaultValue={1024} min={0} name="width">12          <Label>Width</Label>13          <NumberField.Group>14            <NumberField.DecrementButton />15            <NumberField.Input />16            <NumberField.IncrementButton />17          </NumberField.Group>18        </NumberField>19      </TextField>20    </div>21  );22}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Validation

Use isInvalid together with FieldError to surface validation messages.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { FieldError, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function Validation() {8  return (9    <div {...stylex.props(styles.column)}>10      <TextField invalid name="quantity">11        <NumberField required min={0} name="quantity" value={-5} allowOutOfRange>12          <Label required>Quantity</Label>13          <Controls />14          <FieldError match>Quantity must be greater than or equal to 0</FieldError>15        </NumberField>16      </TextField>17      <TextField invalid name="percentage">18        <NumberField19          format={{ style: "percent" }}20          min={0}21          max={1}22          name="percentage"23          step={0.1}24          value={1.5}25          allowOutOfRange26        >27          <Label>Percentage</Label>28          <Controls />29          <FieldError match>Percentage must be between 0 and 100</FieldError>30        </NumberField>31      </TextField>32    </div>33  );34}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

Control the value to synchronize with other components or perform custom formatting.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Button, Description, Label, NumberField, TextField } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { Controls, styles } from "./parts";7
8export function Controlled() {9  const [value, setValue] = useState<number | null>(1024);10  return (11    <div {...stylex.props(styles.column)}>12      <TextField name="width">13        <NumberField min={0} name="width" value={value} onValueChange={setValue}>14          <Label>Width</Label>15          <Controls />16          <Description>Current value: {value}</Description>17        </NumberField>18      </TextField>19      <div {...stylex.props(styles.row)}>20        <Button variant="tertiary" onClick={() => setValue(0)}>21          Reset to 022        </Button>23        <Button variant="tertiary" onClick={() => setValue(2048)}>24          Set to 204825        </Button>26      </div>27    </div>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Step Values

Configure increment/decrement step values for precise control.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7export function WithStep() {8  return (9    <div {...stylex.props(styles.column)}>10      {[1, 5, 10].map((step) => (11        <TextField key={step} name={`step${step}`}>12          <NumberField defaultValue={0} min={0} max={100} step={step} name={`step${step}`}>13            <Label>Step: {step}</Label>14            <Controls />15            <Description>Increments by {step}</Description>16          </NumberField>17        </TextField>18      ))}19    </div>20  );21}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Format Options

Format numbers as currency, percentages, decimals, or units with internationalization support.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { Controls, styles } from "./parts";6
7const formats: {8  name: string;9  label: string;10  description: string;11  value: number;12  format: Intl.NumberFormatOptions;13  max?: number;14  step?: number;15}[] = [16  {17    name: "currency-eur",18    label: "Currency (EUR - Accounting)",19    description: "Accounting format with EUR currency",20    value: 99,21    format: { currency: "EUR", currencySign: "accounting", style: "currency" },22  },23  {24    name: "currency-usd",25    label: "Currency (USD)",26    description: "Standard USD currency format",27    value: 99.99,28    format: { currency: "USD", style: "currency" },29  },30  {31    name: "percentage",32    label: "Percentage",33    description: "Percentage format (0-1, where 0.5 = 50%)",34    value: 0.5,35    format: { style: "percent" },36    max: 1,37    step: 0.01,38  },39  {40    name: "decimal",41    label: "Decimal (2 decimal places)",42    description: "Decimal format with 2 decimal places",43    value: 1234.56,44    format: { maximumFractionDigits: 2, minimumFractionDigits: 2, style: "decimal" },45  },46  {47    name: "unit",48    label: "Unit (Kilograms)",49    description: "Unit format with kilograms",50    value: 1000,51    format: { style: "unit", unit: "kilogram", unitDisplay: "short" },52  },53];54
55export function WithFormatOptions() {56  return (57    <div {...stylex.props(styles.column)}>58      {formats.map((item) => (59        <TextField key={item.name} name={item.name}>60          <NumberField61            defaultValue={item.value}62            min={0}63            max={item.max}64            name={item.name}65            format={item.format}66            step={item.step}67          >68            <Label>{item.label}</Label>69            <Controls />70            <Description>{item.description}</Description>71          </NumberField>72        </TextField>73      ))}74    </div>75  );76}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Form Example

Complete form integration with validation and submission handling.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import {4  Button,5  Description,6  FieldError,7  Form,8  Label,9  NumberField,10  Spinner,11  TextField,12} from "@lenso/ui";13import { useState, type FormEvent } from "react";14import { Controls, styles } from "./parts";15
16export function FormExample() {17  const [value, setValue] = useState<number | null>(null);18  const [isSubmitting, setIsSubmitting] = useState(false);19  const stockAvailable = 3;20  const isOutOfStock = value !== null && value > stockAvailable;21  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {22    event.preventDefault();23    if (value === null || value < 1 || value > stockAvailable || isSubmitting) return;24    setIsSubmitting(true);25    setTimeout(() => {26      console.log("Order submitted:", { quantity: value });27      setValue(null);28      setIsSubmitting(false);29    }, 1500);30  };31  return (32    <Form xstyle={styles.form} onSubmit={handleSubmit}>33      <TextField name="quantity" invalid={isOutOfStock} validationMode="onChange">34        <NumberField35          required36          min={1}37          max={5}38          name="quantity"39          value={value}40          onValueChange={setValue}41        >42          <Label required>Order quantity</Label>43          <Controls />44          {isOutOfStock ? (45            <FieldError match>Only {stockAvailable} items left in stock</FieldError>46          ) : (47            <Description>Only {stockAvailable} items available</Description>48          )}49        </NumberField>50      </TextField>51      <Button52        xstyle={styles.full}53        disabled={value === null || value < 1 || value > stockAvailable}54        isLoading={isSubmitting}55        type="submit"56        variant="primary"57      >58        {isSubmitting ? (59          <>60            <Spinner color="current" size="sm" />61            Processing...62          </>63        ) : (64          "Place Order"65        )}66      </Button>67    </Form>68  );69}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Validation

Implement custom validation logic with controlled values.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, FieldError, Label, NumberField, TextField } from "@lenso/ui";4import { useState } from "react";5import { Controls, styles } from "./parts";6
7export function WithValidation() {8  const [value, setValue] = useState<number | null>(null);9  const isInvalid = value !== null && (value < 0 || value > 1);10  return (11    <TextField12      invalid={isInvalid}13      name="percentage"14      validationMode="onChange"15      xstyle={styles.field}16    >17      <NumberField18        required19        format={{ style: "percent" }}20        min={0}21        max={1}22        name="percentage"23        step={0.1}24        value={value}25        onValueChange={setValue}26        allowOutOfRange27      >28        <Label required>Percentage</Label>29        <Controls />30        {isInvalid ? (31          <FieldError match>Percentage must be between 0 and 100</FieldError>32        ) : (33          <Description>Enter a value between 0 and 100</Description>34        )}35      </NumberField>36    </TextField>37  );38}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Custom Icons

Customize the increment and decrement button icons.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Description, Label, NumberField, TextField } from "@lenso/ui";4import { styles } from "./parts";5
6export function CustomIcons() {7  return (8    <TextField name="width" xstyle={styles.field}>9      <NumberField defaultValue={1024} min={0} name="width">10        <Label>Width (Custom Icons)</Label>11        <NumberField.Group>12          <NumberField.DecrementButton>13            <svg14              aria-hidden="true"15              height="16"16              viewBox="0 0 16 16"17              width="16"18              xmlns="http://www.w3.org/2000/svg"19            >20              <path21                clipRule="evenodd"22                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"23                fill="currentColor"24                fillRule="evenodd"25              />26            </svg>27          </NumberField.DecrementButton>28          <NumberField.Input xstyle={styles.input} />29          <NumberField.IncrementButton>30            <svg31              aria-hidden="true"32              height="16"33              viewBox="0 0 16 16"34              width="16"35              xmlns="http://www.w3.org/2000/svg"36            >37              <path38                clipRule="evenodd"39                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"40                fill="currentColor"41                fillRule="evenodd"42              />43            </svg>44          </NumberField.IncrementButton>45        </NumberField.Group>46        <Description>Custom icon children</Description>47      </NumberField>48    </TextField>49  );50}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Chevrons

Use chevron icons in a vertical layout for a different visual style.

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, NumberField, TextField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "./parts";6
7export function WithChevrons() {8  return (9    <TextField name="amount" xstyle={styles.field}>10      <NumberField11        defaultValue={99}12        min={0}13        name="amount"14        format={{ currency: "EUR", currencySign: "accounting", style: "currency" }}15      >16        <Label>Number field with chevrons</Label>17        <NumberField.Group>18          <NumberField.Input xstyle={styles.flexInput} />19          <div {...stylex.props(styles.chevrons)}>20            <NumberField.IncrementButton xstyle={[styles.chevronButton, styles.up]}>21              <svg22                aria-hidden="true"23                height="11"24                viewBox="0 0 16 16"25                width="11"26                xmlns="http://www.w3.org/2000/svg"27              >28                <path29                  clipRule="evenodd"30                  d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"31                  fill="currentColor"32                  fillRule="evenodd"33                />34              </svg>35            </NumberField.IncrementButton>36            <NumberField.DecrementButton xstyle={[styles.chevronButton, styles.down]}>37              <svg38                aria-hidden="true"39                height="11"40                viewBox="0 0 16 16"41                width="11"42                xmlns="http://www.w3.org/2000/svg"43              >44                <path45                  clipRule="evenodd"46                  d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"47                  fill="currentColor"48                  fillRule="evenodd"49                />50              </svg>51            </NumberField.DecrementButton>52          </div>53        </NumberField.Group>54      </NumberField>55    </TextField>56  );57}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Function

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, NumberField, TextField } from "@lenso/ui";4import { Controls, styles } from "./parts";5
6export function RenderFunction() {7  return (8    <TextField name="width" xstyle={styles.field}>9      <NumberField10        defaultValue={1024}11        min={0}12        name="width"13        render={(props) => <div {...props} data-custom="foo" />}14      >15        <Label>Width</Label>16        <Controls />17      </NumberField>18    </TextField>19  );20}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Customization

Tailwind CSS

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.3import { Label, NumberField, TextField } from "@lenso/ui";4import { styles } from "./parts";5
6export function CustomStyles() {7  return (8    <TextField name="guests" xstyle={styles.guests}>9      <NumberField defaultValue={2} min={1} name="guests" variant="secondary">10        <Label xstyle={styles.label}>Guests</Label>11        <NumberField.Group xstyle={styles.customGroup}>12          <NumberField.DecrementButton xstyle={styles.customButton} />13          <NumberField.Input xstyle={styles.customInput} />14          <NumberField.IncrementButton xstyle={styles.customButton} />15        </NumberField.Group>16      </NumberField>17    </TextField>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

NumberField uses CSS classes that can be customized. Override the component classes to match your design system.

1@layer components {2  .number-field {3    @apply flex flex-col gap-1;4  }5
6  /* When invalid, the description is hidden automatically */7  .number-field[data-invalid="true"] [data-slot="description"],8  .number-field[aria-invalid="true"] [data-slot="description"] {9    @apply hidden;10  }11
12  .number-field__group {13    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;14  }15
16  .number-field__input {17    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;18  }19
20  .number-field__increment-button,21  .number-field__decrement-button {22    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;23  }24}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

Base Classes [!toc]

.number-field – Root container with minimal styling (flex flex-col gap-1)
.number-field__group – Container for input and buttons with border and background styling
.number-field__input – The numeric input field
.number-field__increment-button – Button to increment the value
.number-field__decrement-button – Button to decrement the value

Variant Classes [!toc]

.number-field--primary – Primary variant with shadow (default)
.number-field--secondary – Secondary variant without shadow, suitable for use in surfaces

Note: Child components (Label, Description, FieldError) have their own CSS classes and styling. See their respective documentation for customization options.

Interactive States

NumberField automatically manages these data attributes based on its state:

Invalid: [data-invalid="true"] or [aria-invalid="true"] - Automatically hides the description slot when invalid
Disabled: [data-disabled="true"] - Applied when isDisabled is true
Focus Within: [data-focus-within="true"] - Applied when the input or buttons are focused
Focus Visible: [data-focus-visible="true"] - Applied when focus is visible (keyboard navigation)
Hovered: [data-hovered="true"] - Applied when hovering over buttons

Additional attributes are available through render props (see NumberFieldRenderProps below).

API Reference

NumberField

NumberField inherits all props from React Aria's NumberField component.

Base Props

Prop	Type	Default	Description
`children`	`React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode`	-	Child components (Label, Group, Input, etc.) or render function.
`className`	`string \| (values: NumberFieldRenderProps) => string`	-	CSS classes for styling, supports render props.
`style`	`React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties`	-	Inline styles, supports render props.
`fullWidth`	`boolean`	`false`	Whether the number field should take full width of its container
`id`	`string`	-	The element's unique identifier.
`variant`	`"primary" \| "secondary"`	`"primary"`	Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces.
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>`	-	Overrides the default DOM element with a custom render function.

Value Props

Prop	Type	Default	Description
`value`	`number`	-	Current value (controlled).
`defaultValue`	`number`	-	Default value (uncontrolled).
`onChange`	`(value: number \| undefined) => void`	-	Handler called when the value changes.

Formatting Props

Prop	Type	Default	Description
`formatOptions`	`Intl.NumberFormatOptions`	-	Options for formatting numbers (currency, percent, decimal, unit).
`locale`	`string`	-	Locale for number formatting.

Validation Props

Prop	Type	Default	Description
`isRequired`	`boolean`	`false`	Whether user input is required before form submission.
`isInvalid`	`boolean`	-	Whether the value is invalid.
`validate`	`(value: number) => ValidationError \| true \| null \| undefined`	-	Custom validation function.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation or ARIA attributes.
`validationErrors`	`string[]`	-	Server-side validation errors.

Range Props

Prop	Type	Default	Description
`minValue`	`number`	-	Minimum allowed value.
`maxValue`	`number`	-	Maximum allowed value.
`step`	`number`	`1`	Step value for increment/decrement operations.

State Props

Prop	Type	Default	Description
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed.

Form Props

Prop	Type	Default	Description
`name`	`string`	-	Name of the input element, for HTML form submission.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.

Accessibility Props

Prop	Type	Default	Description
`aria-label`	`string`	-	Accessibility label when no visible label is present.
`aria-labelledby`	`string`	-	ID of elements that label this field.
`aria-describedby`	`string`	-	ID of elements that describe this field.
`aria-details`	`string`	-	ID of elements with additional details.

Composition Components

NumberField works with these separate components that should be imported and used directly:

NumberField.Group - Container for input and buttons
NumberField.Input - The numeric input field
NumberField.IncrementButton - Button to increment the value
NumberField.DecrementButton - Button to decrement the value
Label - Field label component from @lenso/ui
Description - Helper text component from @lenso/ui
FieldError - Validation error message from @lenso/ui

Each of these components has its own props API. Use them directly within NumberField for composition:

1<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>2  <Label>Quantity</Label>3  <NumberField.Group>4    <NumberField.DecrementButton />5    <NumberField.Input />6    <NumberField.IncrementButton />7  </NumberField.Group>8  <Description>Enter a value between 0 and 100</Description>9  <FieldError>Value must be between 0 and 100</FieldError>10</NumberField>

NumberField.Group Props

NumberField.Group inherits props from React Aria's Group component.

Prop	Type	Default	Description
`children`	`React.ReactNode \| (values: GroupRenderProps) => React.ReactNode`	-	Child components (Input, Buttons) or render function.
`className`	`string \| (values: GroupRenderProps) => string`	-	CSS classes for styling.

NumberField.Input Props

NumberField.Input inherits props from React Aria's Input component.

Prop	Type	Default	Description
`className`	`string`	-	CSS classes for styling.
`variant`	`"primary" \| "secondary"`	`"primary"`	Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces.

NumberField.IncrementButton Props

NumberField.IncrementButton inherits props from React Aria's Button component.

Prop	Type	Default	Description
`children`	`React.ReactNode`	`<IconPlus />`	Icon or content for the button. Defaults to plus icon.
`className`	`string`	-	CSS classes for styling.
`slot`	`"increment"`	`"increment"`	Must be set to "increment" (automatically set).

NumberField.DecrementButton Props

NumberField.DecrementButton inherits props from React Aria's Button component.

Prop	Type	Default	Description
`children`	`React.ReactNode`	`<IconMinus />`	Icon or content for the button. Defaults to minus icon.
`className`	`string`	-	CSS classes for styling.
`slot`	`"decrement"`	`"decrement"`	Must be set to "decrement" (automatically set).

Render Props

When using render props with className, style, or children, these values are available:

Prop	Type	Description
`isDisabled`	`boolean`	Whether the field is disabled.
`isInvalid`	`boolean`	Whether the field is currently invalid.
`isReadOnly`	`boolean`	Whether the field is read-only.
`isRequired`	`boolean`	Whether the field is required.
`isFocused`	`boolean`	Whether the field is currently focused (DEPRECATED - use `isFocusWithin`).
`isFocusWithin`	`boolean`	Whether any child element is focused.
`isFocusVisible`	`boolean`	Whether focus is visible (keyboard navigation).
`value`	`number \| undefined`	Current value.
`minValue`	`number \| undefined`	Minimum allowed value.
`maxValue`	`number \| undefined`	Maximum allowed value.
`step`	`number`	Step value for increment/decrement.

See upstream NumberField showcases. Product showcases are not part of the local component runtime.

Label

Renders an accessible label associated with form controls

Description

Provides supplementary text for form fields and other components

FieldError

Displays validation error messages for form fields

NumberField

Usage

Anatomy

Examples

Variants

In Surface

With Description

Required Field

Disabled State

Full Width

Validation

Controlled

Step Values

Format Options

Form Example

With Validation

Custom Icons

With Chevrons

Render Function

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Variant Classes [!toc]

Interactive States

API Reference

NumberField

Base Props

Value Props

Formatting Props

Validation Props

Range Props

State Props

Form Props

Accessibility Props

Composition Components

NumberField.Group Props

NumberField.Input Props

NumberField.IncrementButton Props

NumberField.DecrementButton Props

Render Props

Related Showcases

Related Components