Skip to content
Lenso UI

ColorSwatchPicker 颜色色块选择器

允许用户从预置调色板中选择颜色的 swatch 列表

用法

import { ColorSwatchPicker, parseColor } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";
import { ColorSwatchPicker } from "@lenso/ui";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];export function Basic() {  return (    <ColorSwatchPicker aria-label="Choose a color">      {colors.map((color) => (        <ColorSwatchPicker.Item key={color} color={color}>          <ColorSwatchPicker.Swatch />          <ColorSwatchPicker.Indicator />        </ColorSwatchPicker.Item>      ))}    </ColorSwatchPicker>  );}

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

组件结构

import { ColorSwatchPicker } from '@lenso/ui';
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>);

示例

变体

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";import { SourceSwatches } from "./source";export function Variants() {  return (    <div {...stylex.props(styles.column6)}>      {(["circle", "square"] as const).map((variant) => (        <div key={variant} {...stylex.props(styles.column2)}>          <span {...stylex.props(styles.muted)}>            {variant === "circle" ? "Circle (default)" : "Square"}          </span>          <ColorSwatchPicker aria-label={`${variant} colors`} variant={variant}>            <SourceSwatches />          </ColorSwatchPicker>        </div>      ))}    </div>  );}

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

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";import { SourceSwatches } from "./source";export function Sizes() {  return (    <div {...stylex.props(styles.column6)}>      {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (        <div key={size} {...stylex.props(styles.row4)}>          <span {...stylex.props(styles.width32, styles.muted)}>{size}</span>          <ColorSwatchPicker aria-label={`${size} colors`} size={size}>            <SourceSwatches />          </ColorSwatchPicker>        </div>      ))}    </div>  );}

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

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import { SourceSwatches } from "./source";export function Disabled() {  return (    <ColorSwatchPicker aria-label="Color">      <SourceSwatches disabled />    </ColorSwatchPicker>  );}

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

堆叠布局

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import { SourceSwatches } from "./source";export function StackLayout() {  return (    <ColorSwatchPicker aria-label="Color" layout="stack">      <SourceSwatches />    </ColorSwatchPicker>  );}

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

默认值

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import { SourceSwatches } from "./source";export function DefaultValue() {  return (    <ColorSwatchPicker aria-label="Color" defaultValue="#8B5CF6">      <SourceSwatches />    </ColorSwatchPicker>  );}

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

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker, parseColor } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { styles } from "../color-picker/source.stylex";import { SourceSwatches } from "./source";export function Controlled() {  const [value, setValue] = useState(parseColor("#F43F5E"));  return (    <div {...stylex.props(styles.column)}>      <ColorSwatchPicker aria-label="Color" value={value} onChange={setValue}>        <SourceSwatches />      </ColorSwatchPicker>      <p {...stylex.props(styles.muted)}>        Selected: <span {...stylex.props(styles.medium)}>{value.toString("hex")}</span>      </p>    </div>  );}

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

自定义指示器

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { HeartFill } from "@gravity-ui/icons";import { ColorSwatchPicker } from "@lenso/ui";import { SourceSwatches } from "./source";export function CustomIndicator() {  return (    <ColorSwatchPicker aria-label="Color">      <SourceSwatches indicator={<HeartFill />} />    </ColorSwatchPicker>  );}

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

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. Native RAC render state replaces DOM render interception. */import { ColorSwatchPicker } from "@lenso/ui";import { colors } from "./source";export function RenderFunction() {  return (    <ColorSwatchPicker aria-label="Color" data-custom="foo">      {colors.map((color) => (        <ColorSwatchPicker.Item key={color} color={color}>          {({ isSelected }) => (            <>              <ColorSwatchPicker.Swatch data-selected={isSelected || undefined} />              <ColorSwatchPicker.Indicator />            </>          )}        </ColorSwatchPicker.Item>      ))}    </ColorSwatchPicker>  );}

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

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";/** Adapted from HeroUI v3.2.6. Apache-2.0. */import { ColorSwatchPicker } from "@lenso/ui";import { styles } from "../color-picker/source.stylex";import { SourceSwatches } from "./source";export function CustomStyles() {  return (    <ColorSwatchPicker      aria-label="Color"      xstyle={styles.pickerCustom}      defaultValue="#8B5CF6"      variant="square"    >      <SourceSwatches />    </ColorSwatchPicker>  );}

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

全局 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 类（查看源码样式）：

基础与结构 [!toc]

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

尺寸类 [!toc]

  • .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）

形状变体 [!toc]

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

布局类 [!toc]

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

ColorSwatchPicker.Item

Prop类型默认值描述
colorstring | Color必填swatch 颜色
isDisabledbooleanfalse是否禁用该项
classNamestring-附加 CSS 类
childrenReact.ReactNode-ColorSwatchPicker.Swatch 元素
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>-使用自定义 render 函数覆盖默认 DOM 元素

ColorSwatchPicker.Swatch

Prop类型默认值描述
classNamestring-附加 CSS 类

parseColor

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

import { parseColor } from '@lenso/ui';
// 解析十六进制颜色const red = parseColor('#ff0000');
// 解析 RGBconst green = parseColor('rgb(0, 255, 0)');
// 解析 HSLconst blue = parseColor('hsl(240, 100%, 50%)');

相关组件

ColorSwatch 颜色色块

颜色值的视觉预览，并提供无障碍支持

ColorField 颜色输入框

基于 React Aria ColorField 的颜色输入字段，支持标签、描述与验证

ColorArea 颜色区域

二维颜色选择器，允许用户从渐变区域中选择颜色