ColorPicker 颜色选择器

可组合的颜色选择器，在多个颜色组件间同步颜色值

用法

1import {2  ColorPicker,3  ColorArea,4  ColorSlider,5  ColorSwatch,6  ColorField,7  ColorSwatchPicker,8} from '@lenso/ui';

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

1"use client";2
3import { ColorArea, ColorPicker, ColorSlider, ColorSwatch } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6const styles = stylex.create({7  area: { maxWidth: "100%" },8  slider: { gap: 4, paddingInline: 4 },9  output: { color: "var(--muted)" },10});11export function Basic() {12  return (13    <ColorPicker defaultValue="#0485F7">14      <ColorPicker.Trigger>15        <ColorSwatch size="lg" />16        <span>Pick a color</span>17      </ColorPicker.Trigger>18      <ColorPicker.Popover>19        <ColorArea20          aria-label="Color area"21          xstyle={styles.area}22          colorSpace="hsb"23          xChannel="saturation"24          yChannel="brightness"25        >26          <ColorArea.Thumb />27        </ColorArea>28        <ColorSlider aria-label="Hue" channel="hue" xstyle={styles.slider} colorSpace="hsb">29          <span>Hue</span>30          <ColorSlider.Output xstyle={styles.output} />31          <ColorSlider.Track>32            <ColorSlider.Thumb />33          </ColorSlider.Track>34        </ColorSlider>35      </ColorPicker.Popover>36    </ColorPicker>37  );38}

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

组件结构

ColorPicker 是组合多个颜色组件的可组合组件：

1import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@lenso/ui';2
3export default () => (4  <ColorPicker defaultValue="#0485F7">5    <ColorPicker.Trigger>6      <ColorSwatch />7      <Label>Pick a color</Label>8    </ColorPicker.Trigger>9    <ColorPicker.Popover>10      <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">11        <ColorArea.Thumb />12      </ColorArea>13      <ColorSlider channel="hue" colorSpace="hsb">14        <ColorSlider.Track>15          <ColorSlider.Thumb />16        </ColorSlider.Track>17      </ColorSlider>18    </ColorPicker.Popover>19  </ColorPicker>20);

示例

受控组件

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

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. Gravity Shuffle replaces the source Iconify reference to the same icon. */3import {4  Button,5  ColorArea,6  ColorField,7  ColorPicker,8  ColorSlider,9  ColorSwatch,10  ColorSwatchPicker,11  parseColor,12} from "@lenso/ui";13import { Shuffle } from "@gravity-ui/icons";14import { useState } from "react";15import * as stylex from "@stylexjs/stylex";16import { styles } from "./source.stylex";17const presets = [18  "#ef4444",19  "#f97316",20  "#eab308",21  "#22c55e",22  "#06b6d4",23  "#3b82f6",24  "#8b5cf6",25  "#ec4899",26  "#f43f5e",27];28export function Controlled() {29  const [color, setColor] = useState(parseColor("#325578"));30  function shuffleColor() {31    const hue = Math.floor(Math.random() * 360);32    const saturation = 50 + Math.floor(Math.random() * 50);33    const lightness = 40 + Math.floor(Math.random() * 30);34    setColor(parseColor(`hsl(${hue}, ${saturation}%, ${lightness}%)`));35  }36  return (37    <div {...stylex.props(styles.column)}>38      <ColorPicker value={color} onChange={setColor}>39        <ColorPicker.Trigger>40          <ColorSwatch size="lg" />41          <span>Pick a color</span>42        </ColorPicker.Trigger>43        <ColorPicker.Popover xstyle={styles.popover}>44          <ColorSwatchPicker aria-label="Color presets" xstyle={styles.presets} size="xs">45            {presets.map((preset) => (46              <ColorSwatchPicker.Item key={preset} color={preset}>47                <ColorSwatchPicker.Swatch />48              </ColorSwatchPicker.Item>49            ))}50          </ColorSwatchPicker>51          <ColorArea52            aria-label="Color area"53            xstyle={styles.area}54            colorSpace="hsb"55            xChannel="saturation"56            yChannel="brightness"57          >58            <ColorArea.Thumb />59          </ColorArea>60          <div {...stylex.props(styles.hueRow)}>61            <ColorSlider62              aria-label="Hue slider"63              channel="hue"64              xstyle={styles.flex1}65              colorSpace="hsb"66            >67              <ColorSlider.Track>68                <ColorSlider.Thumb />69              </ColorSlider.Track>70            </ColorSlider>71            <Button72              isIconOnly73              aria-label="Shuffle color"74              size="sm"75              variant="tertiary"76              onClick={shuffleColor}77            >78              <Shuffle {...stylex.props(styles.icon)} />79            </Button>80          </div>81          <ColorField aria-label="Color field">82            <ColorField.Group variant="secondary">83              <ColorField.Prefix>84                <ColorSwatch size="xs" />85              </ColorField.Prefix>86              <ColorField.Input />87            </ColorField.Group>88          </ColorField>89        </ColorPicker.Popover>90      </ColorPicker>91      <p {...stylex.props(styles.selected)}>92        Selected: <span {...stylex.props(styles.medium)}>{color.toString("hex")}</span>93      </p>94    </div>95  );96}

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

带色板

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

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea, ColorPicker, ColorSlider, ColorSwatch, ColorSwatchPicker } from "@lenso/ui";4import { styles } from "./source.stylex";5const presets = [6  "#ef4444",7  "#f97316",8  "#eab308",9  "#22c55e",10  "#06b6d4",11  "#3b82f6",12  "#8b5cf6",13  "#ec4899",14  "#f43f5e",15];16export function WithSwatches() {17  return (18    <ColorPicker defaultValue="#F43F5E">19      <ColorPicker.Trigger>20        <ColorSwatch size="lg" />21        <span>Brand Color</span>22      </ColorPicker.Trigger>23      <ColorPicker.Popover>24        <ColorArea25          aria-label="Color area"26          xstyle={styles.area}27          colorSpace="hsb"28          xChannel="saturation"29          yChannel="brightness"30        >31          <ColorArea.Thumb />32        </ColorArea>33        <ColorSlider aria-label="Hue slider" channel="hue" xstyle={styles.slider} colorSpace="hsb">34          <ColorSlider.Label>Hue</ColorSlider.Label>35          <ColorSlider.Output xstyle={styles.output} />36          <ColorSlider.Track>37            <ColorSlider.Thumb />38          </ColorSlider.Track>39        </ColorSlider>40        <ColorSwatchPicker aria-label="Color presets" xstyle={styles.swatches} size="xs">41          {presets.map((preset) => (42            <ColorSwatchPicker.Item key={preset} color={preset}>43              <ColorSwatchPicker.Swatch />44            </ColorSwatchPicker.Item>45          ))}46        </ColorSwatchPicker>47      </ColorPicker.Popover>48    </ColorPicker>49  );50}

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

带输入字段

使用 ColorField 允许用户编辑单个颜色通道值，配合 Select 切换颜色空间。

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

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea, ColorField, ColorPicker, ColorSlider, ColorSwatch } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { styles } from "./source.stylex";7import { ColorDemoSelect } from "./source";8type Space = "hsb" | "hsl" | "rgb";9const channels = {10  hsb: ["hue", "saturation", "brightness"],11  hsl: ["hue", "saturation", "lightness"],12  rgb: ["red", "green", "blue"],13} as const;14export function WithFields() {15  const [colorSpace, setColorSpace] = useState<Space>("hsl");16  return (17    <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)">18      <ColorPicker.Trigger>19        <ColorSwatch size="lg" />20        <span>Pick a color</span>21      </ColorPicker.Trigger>22      <ColorPicker.Popover xstyle={styles.narrowPopover}>23        <ColorArea24          aria-label="Color area"25          xstyle={styles.area}26          colorSpace="hsb"27          xChannel="saturation"28          yChannel="brightness"29        >30          <ColorArea.Thumb />31        </ColorArea>32        <ColorSlider channel="hue" xstyle={styles.slider} colorSpace="hsb">33          <ColorSlider.Label>Hue</ColorSlider.Label>34          <ColorSlider.Output xstyle={styles.output} />35          <ColorSlider.Track>36            <ColorSlider.Thumb />37          </ColorSlider.Track>38        </ColorSlider>39        <ColorDemoSelect40          label="Color space"41          value={colorSpace}42          options={["hsb", "hsl", "rgb"]}43          onChange={setColorSpace}44          uppercase45        />46        <div {...stylex.props(styles.channelGrid)}>47          {channels[colorSpace].map((channel) => (48            <ColorField49              key={channel}50              aria-label={channel}51              channel={channel}52              colorSpace={colorSpace}53            >54              <ColorField.Group variant="secondary">55                <ColorField.Input />56              </ColorField.Group>57            </ColorField>58          ))}59        </div>60      </ColorPicker.Popover>61    </ColorPicker>62  );63}

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

带滑块

使用多个 ColorSlider 组件调整颜色值的各通道。

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

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorPicker, ColorSlider, ColorSwatch } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { styles } from "./source.stylex";7import { ColorDemoSelect } from "./source";8type Space = "hsb" | "hsl" | "rgb";9const channelProps = {10  hsb: [11    { colorSpace: "hsb", channel: "hue" },12    { colorSpace: "hsb", channel: "saturation" },13    { colorSpace: "hsb", channel: "brightness" },14    { colorSpace: "hsb", channel: "alpha" },15  ],16  hsl: [17    { colorSpace: "hsl", channel: "hue" },18    { colorSpace: "hsl", channel: "saturation" },19    { colorSpace: "hsl", channel: "lightness" },20    { colorSpace: "hsl", channel: "alpha" },21  ],22  rgb: [23    { colorSpace: "rgb", channel: "red" },24    { colorSpace: "rgb", channel: "green" },25    { colorSpace: "rgb", channel: "blue" },26    { colorSpace: "rgb", channel: "alpha" },27  ],28} as const;29export function WithSliders() {30  const [colorSpace, setColorSpace] = useState<Space>("hsl");31  return (32    <ColorPicker defaultValue="hsl(219, 58%, 93%)">33      <ColorPicker.Trigger>34        <ColorSwatch size="lg" />35        <span>Pick a color</span>36      </ColorPicker.Trigger>37      <ColorPicker.Popover xstyle={styles.slidersPopover}>38        <ColorDemoSelect39          label="Color space"40          value={colorSpace}41          options={["hsb", "hsl", "rgb"]}42          onChange={setColorSpace}43          uppercase44        />45        <div {...stylex.props(styles.column2)}>46          {channelProps[colorSpace].map((props) => (47            <ColorSlider48              key={props.channel}49              {...props}50              aria-label={props.channel}51              xstyle={styles.slider}52            >53              <ColorSlider.Label xstyle={styles.capitalize}>{props.channel}</ColorSlider.Label>54              <ColorSlider.Output xstyle={styles.output} />55              <ColorSlider.Track>56                <ColorSlider.Thumb />57              </ColorSlider.Track>58            </ColorSlider>59          ))}60        </div>61      </ColorPicker.Popover>62    </ColorPicker>63  );64}

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

自定义样式

Tailwind CSS

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

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea, ColorPicker, ColorSlider, ColorSwatch } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "./source.stylex";6export function CustomStyles() {7  return (8    <ColorPicker defaultValue="#0485F7">9      <ColorPicker.Trigger xstyle={styles.trigger}>10        <ColorSwatch size="lg" />11        <span {...stylex.props(styles.label)}>Theme color</span>12      </ColorPicker.Trigger>13      <ColorPicker.Popover xstyle={styles.surface}>14        <ColorArea15          aria-label="Color area"16          xstyle={styles.area}17          colorSpace="hsb"18          xChannel="saturation"19          yChannel="brightness"20        >21          <ColorArea.Thumb />22        </ColorArea>23        <ColorSlider channel="hue" xstyle={styles.slider} colorSpace="hsb">24          <ColorSlider.Label>Hue</ColorSlider.Label>25          <ColorSlider.Output xstyle={styles.output} />26          <ColorSlider.Track>27            <ColorSlider.Thumb />28          </ColorSlider.Track>29        </ColorSlider>30      </ColorPicker.Popover>31    </ColorPicker>32  );33}

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

全局 CSS

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

1@layer components {2  .color-picker {3    @apply inline-flex;4  }5
6  .color-picker__trigger {7    @apply inline-flex items-center gap-4 rounded-lg;8  }9
10  .color-picker__popover {11    @apply p-4 rounded-xl;12  }13}

样式参考

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

CSS 类

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

基础类 [!toc]

.color-picker - 基础容器
.color-picker__trigger - 触发按钮
.color-picker__popover - 弹出层容器

交互状态

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

Focus：:focus-visible 或 [data-focus-visible="true"]
Disabled：:disabled 或 [data-disabled="true"]

API 参考

ColorPicker

继承自 React Aria ColorPicker。

Prop	类型	默认值	描述
`value`	`string \| Color`	-	当前颜色值（受控）
`defaultValue`	`string \| Color`	-	默认颜色值（非受控）
`onChange`	`(color: Color) => void`	-	颜色变化时的回调
`children`	`React.ReactNode`	-	颜色选择器内容（Trigger、Popover 等）
`className`	`string`	-	附加 CSS 类

ColorPicker.Trigger

Prop	类型	默认值	描述
`children`	`React.ReactNode \| ((renderProps) => React.ReactNode)`	-	触发器内容或 render prop
`className`	`string`	-	附加 CSS 类

ColorPicker.Popover

Prop	类型	默认值	描述
`placement`	`Placement`	`"bottom left"`	弹出层位置
`children`	`React.ReactNode`	-	弹出层内容
`className`	`string`	-	附加 CSS 类

Color

表示颜色值。完整 API 请参阅 React Aria Color。

Method	Description
`toString(format)`	将颜色转换为指定格式的字符串（hex、rgb、hsl、hsb、css）
`toFormat(format)`	将颜色转换为指定格式并返回新的 Color 对象
`getChannelValue(channel)`	返回指定通道的数值
`withChannelValue(channel, value)`	设置通道数值并返回新的 Color

parseColor

1import { parseColor } from 'react-aria-components';2
3// Parse from string4const color = parseColor('#ff0000');5const hslColor = parseColor('hsl(0, 100%, 50%)');

ColorPicker 颜色选择器

用法

组件结构

示例

受控组件

带色板

带输入字段

带滑块

自定义样式

Tailwind CSS

全局 CSS

样式参考

CSS 类

基础类 [!toc]

交互状态

API 参考

ColorPicker

ColorPicker.Trigger

ColorPicker.Popover

Related Types

Color

parseColor

相关组件