ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

NumberField 数字输入框

数字输入字段，包含增减按钮、校验与国际化格式化能力。

FigmaStorybookReact Aria源代码样式源代码

引入

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

用法

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

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

组件结构

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 允许用户输入数值，并可选择是否显示增减按钮。它支持国际化格式化、校验与键盘导航。

带说明

以像素为单位输入宽度
取值须在 0 到 100 之间
import {Description, Label, NumberField} from "@heroui/react";

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

必填字段

评分范围 1 到 10
import {Description, Label, NumberField} from "@heroui/react";

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

校验

将 isInvalid 与 FieldError 配合使用，以展示校验信息。

数量必须大于或等于 0
百分比必须在 0 到 100 之间
import {FieldError, Label, NumberField} from "@heroui/react";

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

受控

控制值以与其他组件同步，或执行自定义格式化。

当前值：1024
"use client";

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

带校验

在受控数值的基础上实现自定义校验逻辑。

请输入 0 到 100 之间的值
"use client";

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

步进值

配置增减步进值，以实现更精确的控制。

每次增减 1
每次增减 5
每次增减 10
import {Description, Label, NumberField} from "@heroui/react";

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

格式化选项

将数字格式化为货币、百分比、小数或单位，并支持国际化。

欧元会计记账格式
标准美元货币格式
百分比格式（0–1，0.5 表示 50%）
保留 2 位小数格式
千克单位格式
import {Description, Label, NumberField} from "@heroui/react";

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

自定义图标

自定义增减按钮的图标。

自定义图标子元素
import {Description, Label, NumberField} from "@heroui/react";

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

搭配 Chevron

在纵向布局中使用 chevron 图标，以获得不同的视觉风格。

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

export function WithChevrons() {
  return (
    <NumberField

禁用状态

以像素为单位输入宽度
取值须在 0 到 100 之间
import {Description, Label, NumberField} from "@heroui/react";

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

全宽

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

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

变体

NumberField 支持两种视觉变体：

  • primary（默认）— 带阴影的标准样式，适用于大多数场景
  • secondary — 低强调、无阴影的变体，适合用在 Surface 组件内
import {Label, NumberField} from "@heroui/react";

export function Variants() {
  return (
    <div className="flex flex-col gap-4">

在 Surface 内

在 Surface 内使用时，请使用 variant="secondary"，以应用适合表面背景的低强调变体。

以像素为单位输入宽度
取值须在 0 到 100 之间
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">

表单示例

包含校验与提交处理的完整表单集成示例。

仅剩 3 件可购
"use client";

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

自定义渲染函数

"use client";

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

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

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>
  );
}

自定义组件类

NumberField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。

@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 类

  • .number-field – 根容器，样式非常克制（flex flex-col gap-1）
  • .number-field__group – 输入与按钮的容器，包含边框与背景样式
  • .number-field__input – 数字输入字段
  • .number-field__increment-button – 用于增加数值的按钮
  • .number-field__decrement-button – 用于减少数值的按钮
  • .number-field--primary – 带阴影的主变体（默认）
  • .number-field--secondary – 无阴影的次变体，适合用在 surface 上

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。

交互状态

NumberField 会根据状态自动管理以下 data 属性：

  • Invalid：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时会自动隐藏 description 插槽
  • Disabled：[data-disabled="true"] – 当 isDisabled 为 true 时应用
  • Focus Within：[data-focus-within="true"] – 当输入框或按钮聚焦时应用
  • Focus Visible：[data-focus-visible="true"] – 当焦点可见（键盘导航）时应用
  • Hovered：[data-hovered="true"] – 当悬停在按钮上时应用

更多属性可通过渲染 prop 获得（见下方的 NumberFieldRenderProps）。

API 参考

NumberField Props

NumberField 继承 React Aria NumberField 组件的全部 props。

Base Props

Prop类型默认值描述
childrenReact.ReactNode | (values: NumberFieldRenderProps) => React.ReactNode-子组件（Label、Group、Input 等）或渲染函数。
classNamestring | (values: NumberFieldRenderProps) => string-用于样式的 CSS 类，支持渲染 prop。
styleReact.CSSProperties | (values: NumberFieldRenderProps) => React.CSSProperties-行内样式，支持渲染 prop。
fullWidthbooleanfalse数字字段是否占满容器宽度
idstring-元素的唯一标识符。
variant"primary" | "secondary""primary"组件的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Value Props

Prop类型默认值描述
valuenumber-当前值（受控）。
defaultValuenumber-默认值（非受控）。
onChange(value: number | undefined) => void-值变化时触发的事件处理函数。

Formatting Props

Prop类型默认值描述
formatOptionsIntl.NumberFormatOptions-数字格式化选项（货币、百分比、小数、单位等）。
localestring-数字格式化的区域设置。

Validation Props

Prop类型默认值描述
isRequiredbooleanfalse提交表单前是否要求用户输入。
isInvalidboolean-当前值是否无效。
validate(value: number) => ValidationError | true | null | undefined-自定义校验函数。
validationBehavior'native' | 'aria''native'使用原生 HTML 表单校验或 ARIA 属性。
validationErrorsstring[]-服务端校验错误。

Range Props

Prop类型默认值描述
minValuenumber-允许的最小值。
maxValuenumber-允许的最大值。
stepnumber1增减操作的步进值。

State Props

Prop类型默认值描述
isDisabledboolean-是否禁用输入。
isReadOnlyboolean-是否可选中但不可修改。

Form Props

Prop类型默认值描述
namestring-input 元素的名称，用于 HTML 表单提交。
autoFocusboolean-元素渲染后是否应获得焦点。

Accessibility Props

Prop类型默认值描述
aria-labelstring-没有可见标签时的无障碍标签。
aria-labelledbystring-用于标注该字段的元素 ID。
aria-describedbystring-用于描述该字段的元素 ID。
aria-detailsstring-包含更多详情的元素 ID。

Composition Components

NumberField 需要与以下独立组件组合使用，请分别导入并直接使用：

  • NumberField.Group – 输入与按钮的容器
  • NumberField.Input – 数字输入字段
  • NumberField.IncrementButton – 用于增加数值的按钮
  • NumberField.DecrementButton – 用于减少数值的按钮
  • Label – 字段标签组件（@heroui/react）
  • Description – 辅助说明文本组件（@heroui/react）
  • FieldError – 校验错误信息组件（@heroui/react）

这些组件各自拥有 props API。请直接在 NumberField 内组合使用：

<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 继承 React Aria Group 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode | (values: GroupRenderProps) => React.ReactNode-子组件（Input、Buttons）或渲染函数。
classNamestring | (values: GroupRenderProps) => string-用于样式的 CSS 类。

NumberField.Input Props

NumberField.Input 继承 React Aria Input 组件的 props。

Prop类型默认值描述
classNamestring-用于样式的 CSS 类。
variant"primary" | "secondary""primary"输入的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。

NumberField.IncrementButton Props

NumberField.IncrementButton 继承 React Aria Button 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode<IconPlus />按钮的图标或内容。默认为加号图标。
classNamestring-用于样式的 CSS 类。
slot"increment""increment"必须设置为 "increment"（会自动设置）。

NumberField.DecrementButton Props

NumberField.DecrementButton 继承 React Aria Button 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode<IconMinus />按钮的图标或内容。默认为减号图标。
classNamestring-用于样式的 CSS 类。
slot"decrement""decrement"必须设置为 "decrement"（会自动设置）。

NumberFieldRenderProps

在 className、style 或 children 上使用渲染 prop 时，可使用以下值：

Prop类型描述
isDisabledboolean字段是否禁用。
isInvalidboolean字段当前是否无效。
isReadOnlyboolean字段是否只读。
isRequiredboolean字段是否必填。
isFocusedboolean字段是否聚焦（已弃用，请使用 isFocusWithin）。
isFocusWithinboolean是否有任意子元素聚焦。
isFocusVisibleboolean是否为可见焦点（键盘导航）。
valuenumber | undefined当前值。
minValuenumber | undefined允许的最小值。
maxValuenumber | undefined允许的最大值。
stepnumber增减步进值。

Modal 模态框

用于聚焦用户交互与重要内容的对话框遮罩层。

Pagination 分页

分页导航：可组合的页码链接、上一页/下一页按钮与省略号指示器。

本页目录

引入用法组件结构带说明必填字段校验受控带校验步进值格式化选项自定义图标搭配 Chevron禁用状态全宽变体在 Surface 内表单示例自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类交互状态API 参考NumberField PropsBase PropsValue PropsFormatting PropsValidation PropsRange PropsState PropsForm PropsAccessibility PropsComposition ComponentsNumberField.Group PropsNumberField.Input PropsNumberField.IncrementButton PropsNumberField.DecrementButton PropsNumberFieldRenderProps