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

ColorField 颜色输入框

基于 React Aria ColorField 的颜色输入字段，包含标签、说明与校验能力。

StorybookReact Aria源代码样式源代码

引入

import { ColorField, parseColor } from '@heroui/react';

用法

"use client";

import type {Color} from "@heroui/react";

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";

组件结构

import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

export default () => (
  <ColorField>
    <Label />
    <ColorField.Group>
      <ColorField.Prefix>
        <ColorSwatch color="#000000" />
      </ColorField.Prefix>
      <ColorField.Input />
    </ColorField.Group>
    <Description />
    <FieldError />
  </ColorField>
)

ColorField 将标签、颜色输入、说明与错误信息组合为单个可访问组件。

带说明

输入品牌主色
用于高亮与行动按钮
import {ColorField, Description, Label} from "@heroui/react";

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

必填字段

必填项
import {ColorField, Description, Label} from "@heroui/react";

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

校验

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

请输入有效的十六进制颜色
颜色格式无效，请使用十六进制（例如 #FF5733）
import {ColorField, FieldError, Label} from "@heroui/react";

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

通道编辑

通过设置 colorSpace 与 channel，ColorField 支持编辑单个颜色通道（hue、saturation、lightness、红、绿、蓝、alpha）。

分别编辑 HSL 通道：

当前：#7F007F
"use client";

import type {Color} from "@heroui/react";

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";

受控

控制数值以与其他组件或状态管理同步。

当前值：#0485F7
"use client";

import type {Color} from "@heroui/react";

import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";

禁用状态

该颜色字段已禁用
该颜色字段已禁用
"use client";

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

export function Disabled() {

全宽

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

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

变体

ColorField.Group 支持两种视觉变体：

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

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

On Surface

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

选择你的主题色
import {ColorField, Description, Label, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="w-[320px] p-4">

表单示例

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

选择品牌主色
"use client";

import type {Color} from "@heroui/react";

import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";

自定义渲染函数

"use client";

import type {Color} from "@heroui/react";

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";

样式

传入 Tailwind CSS 类

import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';

function CustomColorField() {
  return (
    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Brand Color
      </Label>
      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <ColorField.Prefix>
          <ColorSwatch color="#3B82F6" />
        </ColorField.Prefix>
        <ColorField.Input />
      </ColorField.Group>
      <Description className="text-xs text-default-500">
        Select your brand's primary color.
      </Description>
    </ColorField>
  );
}

自定义组件类

ColorField 的默认样式非常克制。你可以覆盖 .color-field 类来自定义容器样式。

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

    &[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

    [data-slot="label"] {
      @apply w-fit;
    }

    [data-slot="description"] {
      @apply px-1;
    }
  }
}

CSS 类

  • .color-field – 根容器，样式非常克制（flex flex-col gap-1）

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。ColorField.Group 的样式见下文 API 参考中的 ColorField.Group Styling 小节。

交互状态

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

  • Invalid：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时会自动隐藏 description 插槽
  • Required：[data-required="true"] – 当 isRequired 为 true 时应用
  • Disabled：[data-disabled="true"] – 当 isDisabled 为 true 时应用
  • Focus Within：[data-focus-within="true"] – 当任意子输入聚焦时应用

API 参考

ColorField Props

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

Base Props

Prop类型默认值描述
childrenReact.ReactNode | (values: ColorFieldRenderProps) => React.ReactNode-子组件（Label、ColorField.Group 等）或渲染函数。
classNamestring | (values: ColorFieldRenderProps) => string-用于样式的 CSS 类，支持渲染 prop。
styleReact.CSSProperties | (values: ColorFieldRenderProps) => React.CSSProperties-行内样式，支持渲染 prop。
fullWidthbooleanfalse颜色字段是否占满容器宽度
idstring-元素的唯一标识符。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Value Props

Prop类型默认值描述
valueColor | null-当前值（受控）。
defaultValueColor | null-默认值（非受控）。
onChange(color: Color | null) => void-值变化时触发的事件处理函数。

Channel Props

Prop类型默认值描述
colorSpaceColorSpace-当提供 channel 时，颜色字段所处的色彩空间。
channelColorChannel-要编辑的颜色通道。未提供时编辑十六进制值。

Validation Props

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

State Props

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

Form Props

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

Accessibility Props

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

Composition Components

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

  • Label – 字段标签组件（@heroui/react）
  • ColorField.Group – 颜色输入分组组件（见下文）
  • ColorField.Input – ColorField.Group 内的输入元素
  • ColorField.Prefix / ColorField.Suffix – 输入组的前缀与后缀插槽
  • ColorSwatch – 颜色预览组件（@heroui/react）
  • Description – 辅助说明文本组件（@heroui/react）
  • FieldError – 校验错误信息组件（@heroui/react）

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

import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

<ColorField
  isRequired
  isInvalid={hasError}
  value={color}
  onChange={setColor}
>
  <Label>Brand Color</Label>
  <ColorField.Group>
    <ColorField.Prefix>
      <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} />
    </ColorField.Prefix>
    <ColorField.Input />
  </ColorField.Group>
  <Description>Select your brand's primary color.</Description>
  <FieldError>Please enter a valid color.</FieldError>
</ColorField>

Color Types

ColorField 使用来自 React Aria Components 的 Color 对象：

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

// Parse from hex string
const color = parseColor('#3B82F6');

// Get hex string from color
const hex = color.toString('hex'); // "#3b82f6"

// Get RGB values
const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"

// Use in ColorField
<ColorField value={color} onChange={setColor}>
  {/* ... */}
</ColorField>

ColorFieldRenderProps

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

Prop类型描述
isDisabledboolean字段是否禁用。
isInvalidboolean字段当前是否无效。
isReadOnlyboolean字段是否只读。
isRequiredboolean字段是否必填。
isFocusedboolean字段是否聚焦。
isFocusWithinboolean是否有任意子元素聚焦。
isFocusVisibleboolean是否为可见焦点（键盘导航）。

ColorField.Group Props

ColorField.Group 接受 React Aria Group 组件的全部 props，以及：

Prop类型默认值描述
classNamestring-与组件样式合并的 Tailwind CSS 类。
fullWidthbooleanfalse颜色输入组是否占满容器宽度
variant"primary" | "secondary""primary"组件的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

ColorField.Input Props

ColorField.Input 接受 React Aria Input 组件的全部 props，以及：

Prop类型默认值描述
classNamestring-与组件样式合并的 Tailwind CSS 类。
placeholderstring-为空时显示的占位符文本。

ColorField.Prefix Props

ColorField.Prefix 接受标准 HTML div 属性：

Prop类型默认值描述
classNamestring-与组件样式合并的 Tailwind CSS 类。
childrenReactNode-前缀插槽中要展示的内容。

ColorField.Suffix Props

ColorField.Suffix 接受标准 HTML div 属性：

Prop类型默认值描述
classNamestring-与组件样式合并的 Tailwind CSS 类。
childrenReactNode-后缀插槽中要展示的内容。

ColorField.Group Styling

自定义组件类

基础类会作用于每个实例。你可以在 @layer components 中一次性覆盖它们。

@layer components {
  .color-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-field-hover;
    }

    &[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

    &[data-invalid="true"] {
      @apply status-invalid-field;
    }

    &[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

  .color-input-group__input {
    @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .color-input-group__prefix,
  .color-input-group__suffix {
    @apply shrink-0 text-field-placeholder flex items-center;
  }
}

ColorField.Group CSS Classes

  • .color-input-group – 根容器样式
  • .color-input-group__input – 输入区域包裹样式
  • .color-input-group__prefix – 前缀元素样式
  • .color-input-group__suffix – 后缀元素样式

ColorField.Group Interactive States

  • Hover：:hover 或 [data-hovered="true"]
  • Focus Within：[data-focus-within="true"] 或 :focus-within
  • Invalid：[data-invalid="true"]（也会与 aria-invalid 同步）
  • Disabled：[data-disabled="true"] 或 [aria-disabled="true"]

ColorArea 颜色区域

二维颜色选择器，用户可在渐变区域内选取颜色。

ColorSlider 颜色滑块

ColorSlider 允许用户调整颜色值的单个通道。

本页目录

引入用法组件结构带说明必填字段校验通道编辑受控禁用状态全宽变体On Surface表单示例自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类交互状态API 参考ColorField PropsBase PropsValue PropsChannel PropsValidation PropsState PropsForm PropsAccessibility PropsComposition ComponentsColor TypesColorFieldRenderPropsColorField.Group PropsColorField.Input PropsColorField.Prefix PropsColorField.Suffix PropsColorField.Group Styling自定义组件类ColorField.Group CSS ClassesColorField.Group Interactive States