# ChromaPanel

> ChromaPanel 是始终可见的 React 颜色选择器组件，提供色轮、滑块、调色板、图片和预设色模式，适合放在侧边栏、模态框和页面中。

Source: https://chroma-panel.jscrate.dev/zh/react/components/chroma-panel
Last updated: 2026-09-21

`ChromaPanel` 就是 React 颜色选择器组件本身，直接渲染在原位，而不是藏在按钮后面。它包含标题栏、每个模式各自的标签页、当前模式的内容，以及底栏。底栏里有当前颜色预览、最近使用的颜色、复制按钮，浏览器支持时还有取色器。如果希望选择器一直留在屏幕上，而不是按需打开，就用它。

默认显示全部五种模式，依次是[色轮](https://chroma-panel.jscrate.dev/zh/react/modes/wheel)、滑块、调色板、图片和预设色。通过 `modes` 可以选择显示哪些标签页，以及它们的顺序。只有一种模式时，不显示标签栏。[ColorInput](https://chroma-panel.jscrate.dev/zh/react/components/color-input) 在弹出层中打开的正是这个面板，所以你在这里做的配置对它同样有效。如果要用同一个值驱动多个面板，就给它们传入同一个[颜色 store](https://chroma-panel.jscrate.dev/zh/react/utils/use-color-store)。

## 结构

```tsx
import { ChromaPanel } from "chroma-panel";

<ChromaPanel defaultValue="#3366cc" modes={["wheel"]} showTitleBar={false} />;
```

## 演示

```tsx
"use client";

import { ChromaPanel } from "chroma-panel";

export default function ChromaPanelDemo() {
  return <ChromaPanel defaultValue="#3366cc" injectStyles={false} />;
}
```

## API 参考

v1 新增的元数据回调是对原有回调的补充。`onValueChange` 和 `onValueCommit` 的第二个参数是 `{ phase, source }`。source 标明了变更的来源：指针、键盘、输入框、色块、图片、取色器、最近使用的颜色，或是代码调用。

```tsx
<ChromaPanel onValueCommit={(color, meta) => save(color.css, meta.source)} />
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string \| Hsva` | — | The color, when you keep it in your own state. |
| `defaultValue` | `string \| Hsva` | `'#3366cc'` | The starting color, when you want the panel to keep it. |
| `onChange` | `(color: ColorChangeResult) => void` | — | Fires continuously while a drag is in progress. |
| `onChangeComplete` | `(color: ColorChangeResult) => void` | — | Fires once when the drag ends. Use it for saving, undo entries and network calls. |
| `onValueChange` | `(color: ColorChangeResult, meta: ColorChangeMeta) => void` | — | Fires continuously with interaction metadata, including the change source. |
| `onValueCommit` | `(color: ColorChangeResult, meta: ColorChangeMeta) => void` | — | Fires once per completed interaction with phase and source metadata. |
| `modes` | `readonly (ModeId \| string \| PickerMode)[]` | `all five` | Which tabs appear, in the order you list them. |
| `mode` | `string` | — | The open tab, when you control it. |
| `defaultMode` | `string` | `first mode` | The tab to open on. |
| `onModeChange` | `(mode: string) => void` | — | Fires when the reader switches tabs. |
| `format` | `ColorFormat` | `'hex'` | Sets the `css` string on the change result, and the value a form submits. |
| `showAlpha` | `boolean` | `true` | Turn off when opacity is not allowed. |
| `showEyedropper` | `boolean` | `true` | Turn off to hide the eyedropper even where it is supported. |
| `showCopyButton` | `boolean` | `true` | Show a button that copies the color in the configured format. |
| `showRecentColors` | `boolean` | `true` | Turn off in a one-shot picker. |
| `recentColors` | `string[]` | — | The recent-color history, when you keep it. Persist it yourself to carry the list between sessions. |
| `defaultRecentColors` | `string[]` | `[]` | The starting history, when you want the panel to keep it. |
| `onRecentColorsChange` | `(colors: string[]) => void` | — | Fires with the whole list whenever a color is added to it. |
| `palettes` | `ColorPalette[]` | `built-in set` | Replaces the palette swatches with your own. |
| `pencils` | `string[]` | `built-in 120-color grid` | Replaces the pencil grid. |
| `modeProps` | `Record<string, Record<string, unknown>>` | — | Props spread onto one mode's panel, keyed by mode id. Lets a custom mode take props without the panel knowing about it. |
| `imageOptions` | `ExtractOptions` | — | Shorthand for `modeProps.image.extractOptions`. |
| `disabled` | `boolean` | `false` | Makes the panel read-only. |
| `theme` | `"dark" \| "light"` | `system` | Forces one theme instead of following the OS. |
| `showTitleBar` | `boolean` | `true` | Turn off for an inline panel with no chrome. |
| `title` | `string` | `'Colors'` | The title bar text. |
| `onClose` | `() => void` | — | Fires when the red window control is used. An inline panel has nothing to close, so that control is dimmed until you pass this. |
| `collapsed` | `boolean` | — | Whether the panel is collapsed to its title bar, when you control it. |
| `defaultCollapsed` | `boolean` | `false` | Whether it starts collapsed. Collapsing hides the body with CSS rather than unmounting, so nothing is lost. |
| `onCollapsedChange` | `(collapsed: boolean) => void` | — | Fires when the yellow window control is used. |
| `size` | `PanelSize` | — | The panel size, when you control it. |
| `defaultSize` | `PanelSize` | `'default'` | The starting size. `'expanded'` widens the panel, and the wheel with it. |
| `onSizeChange` | `(size: PanelSize) => void` | — | Fires when the green window control is used. |
| `injectStyles` | `boolean` | `true` | Turn off when you import `chroma-panel/style.css` yourself, as this site does. |
| `className` | `string` | — | Class applied to the panel root. |
| `classNames` | `ChromaClassNames` | — | Classes applied per part. |
| `style` | `React.CSSProperties` | — | Inline styles on the panel root. Setting the `--cp-*` custom properties here themes a single panel. |
| `store` | `ColorStore` | — | An external color store, for driving several panels from one color. |

## 相关内容

- [ColorInput](https://chroma-panel.jscrate.dev/zh/react/components/color-input)：同一个面板，放在色块按钮后面
- [主题](https://chroma-panel.jscrate.dev/zh/react/handbook/theming)：用 CSS 变量设置面板的尺寸和颜色
- [受控与非受控](https://chroma-panel.jscrate.dev/zh/react/handbook/controlled)：决定哪些 prop 由你自己管理
- [入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)：只导入你列出的模式