# SwatchGrid

> SwatchGrid 把 React 颜色色块排成网格，点击某个色块即可设置颜色并标记为选中。调色板和预设色模式都基于它构建。

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

`SwatchGrid` 把一组颜色排成一行行 React 色块按钮，并把它们和面板连接起来。点击一个色块，会设置当前颜色并提交。与当前颜色一致的色块处于按下状态：周围会画一个圆环，屏幕阅读器也会播报为已按下。有三个内置模式用到了这个网格：[调色板模式](https://chroma-panel.jscrate.dev/zh/react/modes/palettes)、[预设色模式](https://chroma-panel.jscrate.dev/zh/react/modes/pencils)，以及图片模式中提取出的颜色。

如果自定义模式要展示一组颜色，比如你的品牌色，就可以用它。`label` 是给屏幕阅读器的列表名称；条目设置了 `name` 时，它就是对应色块的名称。`columns` 设置每行放几个色块，默认为 10。默认的 `"spaced"` 变体在色块之间留出间隙，`"mosaic"` 则让色块紧挨在一起，预设色模式就是这样。

## 结构

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

<SwatchGrid
  label="Brand"
  columns={6}
  swatches={[
    { color: "#3366cc", name: "Brand blue" },
    { color: "#cc3366", name: "Brand pink" },
  ]}
/>;
```

> **只能在面板内使用**
>
> 内置模式就是由这些基础组件搭起来的。它通过 `usePanel()` 读取颜色，所以只能放在 `ChromaPanel` 里使用，通常用在[自定义模式](https://chroma-panel.jscrate.dev/zh/react/modes/custom)中。如果要在面板之外做颜色选择器，请使用[颜色 store 和相关 hook](https://chroma-panel.jscrate.dev/zh/react/utils/use-color-store)。

## API 参考

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `swatches` (required) | `SwatchEntry[]` | — | The colors, each optionally with a name. |
| `columns` | `number` | `10` | Swatches per row. The pencils grid uses 12. |
| `variant` | `SwatchVariant` | `'spaced'` | `'spaced'` leaves gaps between swatches; the tighter variants butt them together, as the pencil grid does. |
| `round` | `boolean` | `false` | Render every swatch as a circle. |
| `label` (required) | `string` | — | Accessible name for the grid, such as the palette's name. |
| `className` | `string` | — | Class on the grid. |

## 相关内容

- [Swatch](https://chroma-panel.jscrate.dev/zh/react/components/swatch)：单个色块，配合你自己的 `onSelect`
- [调色板模式](https://chroma-panel.jscrate.dev/zh/react/modes/palettes)：以带间隙网格展示的具名色块组
- [预设色模式](https://chroma-panel.jscrate.dev/zh/react/modes/pencils)：mosaic 变体的 120 色网格
- [图片模式](https://chroma-panel.jscrate.dev/zh/react/modes/image)：从照片中提取的颜色网格