# 快速开始

> 安装 chroma-panel，以弹出层或内联面板的形式添加 React 颜色选择器。可以先用非受控写法，也可以把颜色值放进自己的状态里。

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

安装软件包，渲染 `ColorInput`，就有了一个能用的 React 颜色选择器。如果希望选择器一直显示在页面上，改用 `ChromaPanel`。

## 安装

```bash
npm install chroma-panel
```

不需要导入 CSS，也不需要配置 provider。在 Next.js 和其他服务端渲染的应用里也是如此，详见[服务端渲染](https://chroma-panel.jscrate.dev/zh/react/handbook/server-rendering)。

## 添加颜色输入框

`ColorInput` 会渲染一个色块按钮，点击后在弹出层中打开面板。

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

<ColorInput defaultValue="#3366cc" />;
```

```tsx
"use client";

import { ColorInput } from "chroma-panel";
import { useState } from "react";

export default function ColorInputDemo() {
  const [color, setColor] = useState("#3366cc");

  return (
    <div className="flex items-center gap-3">
      <ColorInput
        value={color}
        onChange={(c) => setColor(c.hex)}
        injectStyles={false}
      />
      <span className="font-mono text-sm text-muted-foreground">{color}</span>
    </div>
  );
}
```

## 控制颜色值

传入 `value` 并处理 `onChange`，颜色就保存在你自己的状态里。如果改传 `defaultValue`，则由面板替你保存。

```tsx
import { useState } from "react";
import { ColorInput, type ColorChangeResult } from "chroma-panel";

export function BrandPicker() {
  const [color, setColor] = useState<string>("#3366cc");

  const handleChange = (result: ColorChangeResult): void => {
    setColor(result.hex);
  };

  return <ColorInput value={color} onChange={handleChange} />;
}
```

拖动过程中，`onChange` 会持续触发；松手时，`onChangeComplete` 只触发一次。保存数据、记录撤销步骤和发起网络请求都应该放在后者里。两者的区别见 [onChange 与 onChangeComplete](https://chroma-panel.jscrate.dev/zh/react/handbook/controlled#onchange-vs-onchangecomplete)。

## 内联面板

`ChromaPanel` 就是去掉弹出层的同一个面板，适合直接放在页面上。它的 props 列在 [ChromaPanel 参考文档](https://chroma-panel.jscrate.dev/zh/react/components/chroma-panel)中。

```tsx
"use client";

import { ChromaPanel } from "chroma-panel";

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

## 更小的打包体积

导入 `chroma-panel` 会注册全部五种模式。如果只用得到一两种，可以导入面板外壳，再自行添加模式。

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

<ChromaPanel modes={[wheelMode]} />;
```

这样体积是 15.0 kB，而不是 23.1 kB。每种模式都有自己的入口，详见[入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)。

```tsx
"use client";

import { ChromaPanel } from "chroma-panel";

export default function ChromaPanelWheelDemo() {
  return (
    <ChromaPanel
      defaultValue="#3366cc"
      modes={["wheel"]}
      showTitleBar={false}
      injectStyles={false}
    />
  );
}
```

## 下一步

- [主题](https://chroma-panel.jscrate.dev/zh/react/handbook/theming)：修改面板的外观
- [受控与非受控](https://chroma-panel.jscrate.dev/zh/react/handbook/controlled)：哪些 props 由你管理
- [ColorInput](https://chroma-panel.jscrate.dev/zh/react/components/color-input)：完整的 prop 参考
- [表单](https://chroma-panel.jscrate.dev/zh/react/handbook/forms)：随表单提交颜色
- [常见问题](https://chroma-panel.jscrate.dev/zh/react/overview/faq)：常见问题的简短解答