NumberFieldUpdated

Import

import { NumberField } from '@heroui/react';

Usage

import {Label, NumberField} from "@heroui/react";

export function Basic() {
  return (
    <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width">

Anatomy

import {NumberField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <NumberField>
    <Label />
    <NumberField.Group>
      <NumberField.DecrementButton />
      <NumberField.Input />
      <NumberField.IncrementButton />
    </NumberField.Group>
    <Description />
    <FieldError />
  </NumberField>
)

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

With Description

import {Description, Label, NumberField} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Required Field

import {Description, Label, NumberField} from "@heroui/react";

export function Required() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Validation

Use isInvalid together with FieldError to surface validation messages.

import {FieldError, Label, NumberField} from "@heroui/react";

export function Validation() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Controlled

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

"use client";

import {Button, Description, Label, NumberField} from "@heroui/react";
import React from "react";

With Validation

Implement custom validation logic with controlled values.

"use client";

import {Description, FieldError, Label, NumberField} from "@heroui/react";
import React from "react";

Step Values

Configure increment/decrement step values for precise control.

import {Description, Label, NumberField} from "@heroui/react";

export function WithStep() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Format Options

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

import {Description, Label, NumberField} from "@heroui/react";

export function WithFormatOptions() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Custom Icons

Customize the increment and decrement button icons.

import {Description, Label, NumberField} from "@heroui/react";

export function CustomIcons() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

With Chevrons

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

import {Label, NumberField} from "@heroui/react";

export function WithChevrons() {
  return (
    <NumberField

Disabled State

import {Description, Label, NumberField} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">

Full Width

import {Label, NumberField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">

On Surface

When used inside a Surface component, NumberField automatically applies on-surface styling.

import {Description, Label, NumberField, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-[280px] flex-col gap-4 rounded-3xl p-6">

Form Example

Complete form integration with validation and submission handling.

"use client";

import {Button, Description, FieldError, Form, Label, NumberField, Spinner} from "@heroui/react";
import React from "react";

Styling

Passing Tailwind CSS classes

import {NumberField, Label} from '@heroui/react';

function CustomNumberField() {
  return (
    <NumberField className="gap-2">
      <Label className="text-sm font-semibold">Quantity</Label>
      <NumberField.Group className="rounded-xl border-2">
        <NumberField.DecrementButton className="bg-gray-100" />
        <NumberField.Input className="text-center font-bold" />
        <NumberField.IncrementButton className="bg-gray-100" />
      </NumberField.Group>
    </NumberField>
  );
}

Customizing the component classes

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

@layer components {
  .number-field {
    @apply flex flex-col gap-1;
  }

  /* When invalid, the description is hidden automatically */
  .number-field[data-invalid="true"] [data-slot="description"],
  .number-field[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

  .number-field__group {
    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
  }

  .number-field__input {
    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;
  }

  .number-field__increment-button,
  .number-field__decrement-button {
    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;
  }
}

CSS Classes

• .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
• .number-field__group--on-surface – Applied when used inside a Surface component

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 Props

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

Base Props

Value Props

Formatting Props

Validation Props

Range Props

State Props

Form Props

Accessibility Props

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 @heroui/react
• Description - Helper text component from @heroui/react
• FieldError - Validation error message from @heroui/react

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

<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>
  <Label>Quantity</Label>
  <NumberField.Group>
    <NumberField.DecrementButton />
    <NumberField.Input />
    <NumberField.IncrementButton />
  </NumberField.Group>
  <Description>Enter a value between 0 and 100</Description>
  <FieldError>Value must be between 0 and 100</FieldError>
</NumberField>

NumberField.Group Props

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

NumberField.Input Props

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

NumberField.IncrementButton Props

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

NumberField.DecrementButton Props

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

NumberFieldRenderProps

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