用法

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

组件结构

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

export default () => (
  <ColorSwatchPicker>
    <ColorSwatchPicker.Item color="#F43F5E">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#D946EF">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#8B5CF6">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
  </ColorSwatchPicker>
);

示例

变体

圆形（默认）

方形

尺寸

特小

小

中

大

特大

禁用

堆叠布局

默认值

受控组件

已选：#F43F5E

自定义指示器

渲染函数

自定义样式

Tailwind CSS

全局 CSS

可使用 @layer components 指令自定义 ColorSwatchPicker 组件类。了解更多。

@layer components {
  .color-swatch-picker {
    @apply gap-4;
  }

  .color-swatch-picker__item {
    @apply shadow-md;
  }

  .color-swatch-picker__swatch {
    @apply border-2 border-white;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ColorSwatchPicker 组件使用以下 CSS 类（查看源码样式）：

基础与结构

.color-swatch-picker - 基础容器（flex 布局）
.color-swatch-picker__item - 单个 swatch 包裹层
.color-swatch-picker__swatch - swatch 视觉元素

尺寸类

.color-swatch-picker--xs - 特小（16px）
.color-swatch-picker--sm - 小（24px）
.color-swatch-picker--md - 中（32px，默认）
.color-swatch-picker--lg - 大（36px）
.color-swatch-picker--xl - 特大（40px）

形状变体

.color-swatch-picker--circle - 圆形（默认）
.color-swatch-picker--square - 圆角方形

布局类

.color-swatch-picker--grid - 横向换行网格（默认）
.color-swatch-picker--stack - 纵向堆叠

交互状态

组件同时支持 CSS 伪类与 data 属性：

Hover：:hover 或 [data-hovered="true"] - 缩放至 1.1（仅在未选中时）
Focus：:focus-visible 或 [data-focus-visible="true"] - 焦点环
Selected：[data-selected="true"] - 与 swatch 同色的内边框
Disabled：[data-disabled="true"] - 降低透明度

API 参考

ColorSwatchPicker

继承自 React Aria ColorSwatchPicker。

Prop	类型	默认值	描述
`value`	`string \| Color`	-	当前选中颜色（受控）
`defaultValue`	`string \| Color`	-	默认选中颜色（非受控）
`onChange`	`(value: Color) => void`	-	选中变化时的回调
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	swatch 尺寸
`variant`	`"circle" \| "square"`	`"circle"`	swatch 形状
`layout`	`"grid" \| "stack"`	`"grid"`	布局方向
`className`	`string`	-	附加 CSS 类
`children`	`React.ReactNode`	-	ColorSwatchPicker.Item 元素
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>`	-	使用自定义 render 函数覆盖默认 DOM 元素

ColorSwatchPicker.Item

Prop	类型	默认值	描述
`color`	`string \| Color`	必填	swatch 颜色
`isDisabled`	`boolean`	`false`	是否禁用该项
`className`	`string`	-	附加 CSS 类
`children`	`React.ReactNode`	-	ColorSwatchPicker.Swatch 元素
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>`	-	使用自定义 render 函数覆盖默认 DOM 元素

ColorSwatchPicker.Swatch

Prop	类型	默认值	描述
`className`	`string`	-	附加 CSS 类

parseColor

为方便使用，从 React Aria Components 重新导出 parseColor 函数：

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

// 解析十六进制颜色
const red = parseColor('#ff0000');

// 解析 RGB
const green = parseColor('rgb(0, 255, 0)');

// 解析 HSL
const blue = parseColor('hsl(240, 100%, 50%)');