---
title: "Colour swatches"
description: "Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker."
url: "https://ewels.github.io/starlight-codeblocks/features/colour-swatches/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/colour-swatches.md"
section: "Make code easier to read"
site: "starlight-codeblocks documentation"
context: "This page is from the documentation of starlight-codeblocks. A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site."
index: "https://ewels.github.io/starlight-codeblocks/llms.txt"
---

# Colour swatches

> Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker.

A hex value such as `#ff5f1f` tells most readers little about the colour. The plugin puts a small swatch before each CSS colour in a code block, in the colour itself. Swatches are on for every code block, so you do not add an attribute.

````md
```css
.button {
  color: #ffffff;
  background: rebeccapurple;
  border: 1px solid rgb(102 51 153 / 50%);
}
```
````

Each value keeps its text, and the swatch comes before it. Hover over a colour to show it on a chip in its own colour. Click a colour to copy it.

## Syntax

Each attribute goes on the code block fence line.

| Syntax | What it does |
|---|---|
| `swatches=false` | Turns off the swatches for the block. |
| `swatches` | Turns on the swatches for a block of a language outside `swatches.languages`. |
| `swatches.shape="square"` | Draws square swatches in the block. |
| `swatches.shape="rounded"` | Draws swatches with rounded corners in the block. |
| `swatches.shape="circle"` | Draws round swatches in the block. |
| `swatches.match="all"` | Shows a swatch for every hex colour and colour function in the block. |
| `swatches.match="value"` | Shows a swatch only for colours that look like values in the block. |

## Examples

### Every kind of colour

Hex colours, the CSS colour functions and the colour names all get a swatch:

````md
```css
:root {
  --brand: #ff5f1f;
  --link: rgb(37 99 235);
  --success: hsl(142deg 71% 45%);
  --muted: hwb(220 60% 30%);
  --warm: lab(62% 45 60);
  --cool: lch(55% 60 260);
  --mint: oklab(0.8 -0.12 0.04);
  --violet: oklch(60% 0.2 300);
  --wide: color(display-p3 0.2 0.7 0.4);
  --shadow: black;
}
```
````

### Swatch shapes

`swatches.shape` sets the shape for one block. The `swatches.shape` option sets it for the site:

````md
```css swatches.shape="square"
.tag { background: #22c55e; }
```

```css swatches.shape="rounded"
.tag { background: #22c55e; }
```

```css swatches.shape="circle"
.tag { background: #22c55e; }
```
````

### Colours with transparency

A colour with an alpha value shows a checkerboard through its swatch:

````md
```css
.overlay {
  background: rgb(15 23 42 / 40%);
  border-color: #ff5f1f80;
  box-shadow: 0 4px 12px hsl(0 0% 0% / 0.25);
}
```
````

### Colours in other languages

Outside stylesheets, the plugin finds colours only where they look like values: in quotes, or after a `:`, `=` or `,`. A comment such as `// TODO #add` keeps its text:

````md
```js
// TODO #add a dark theme
const theme = {
  text: '#1e1e2e',
  accent: 'tomato',
};
```
````

### Every colour in a block

Some languages put colours where they do not look like values, such as after a `|`. Add `swatches.match="all"` to show a swatch for every hex colour and colour function:

````md
```text swatches.match="all"
%%metro line: main | Main | #4caf50
%%metro line: qc | Quality Control | #2196f3 | dashed
```
````

### Turn off swatches for one block

Add `swatches=false` to the fence line. The fence line is the first line of the code block, with the language:

````md
```css swatches=false
:root { --accent: #ff5f1f; }
```
````

### Colours in the prose

With the `swatches.prose` option, colours in the text of a page also get a swatch. This site turns it on:

```md
The brand colour is #ff5f1f. Use `rebeccapurple` for links.
```

## Behaviour

- Colours:
  - Hex colours with three, four, six or eight digits, and the CSS colour names, such as `rebeccapurple`.
  - The colour functions `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()` and `color()`.
  - A colour function gets a swatch only when it has numbers in it. `rgb(var(--r), 0, 0)` has no swatch, because the plugin cannot know its colour.
  - A colour with transparency shows a checkerboard through the swatch.
- What is not a colour:
  - In CSS, Sass, Less and Stylus blocks, ID selectors such as `#bad { }` and classes such as `.red`.
  - Variables such as `$green` and `--blue`, and SVG references such as `url(#fade)`.
  - In other languages, colour names that are not in quotes, such as `paint(red)`.
  - In other languages, hex that does not look like a value, such as `// TODO #add`. The `swatches.delimiters` option adds text, such as `|`, that can come before or after a value.
  - With `swatches.match="all"`, issue numbers such as #123 and words such as #add that are not in quotes.
  - In the prose, issue numbers such as #123, tags such as #cafe, and colour names such as red that are not inline code.
- Hover and copy:
  - Hovering over a colour shows it on a chip in its own colour, with a darker border. The text turns black or white, whichever reads on the colour.
  - After a short pause, **Click to copy** shows next to the colour.
  - Clicking a colour copies its value, and **Copied** shows next to it. A colour is a button, so you can also move to it with Tab and press Enter or Space.
  - The swatches copy no text. The copy button and a selection copy the code as written.
- Without JavaScript:
  - The swatches and the hover tint work without JavaScript. Copy needs JavaScript, and without it a colour is plain text.

## Options

### `swatches`

Shows a swatch of the colour before each CSS colour in code. Set it to `false` to turn the feature off.

- Type: `false | object`
- Default: On

### `swatches.languages`

Languages that get swatches. `swatches` on the fence line turns them on for one block of another language.

- Type: `'all' | string[]`
- Default: `'all'`

### `swatches.formats`

The kinds of colour that get swatches. `rgb` also covers `rgba()`, and `hsl` covers `hsla()`. `named` is the CSS colour names, such as `rebeccapurple`.

- Type: `Array<'hex' | 'rgb' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'color' | 'named'>`
- Default: `['hex','rgb','hsl','hwb','lab','lch','oklab','oklch','color','named']`

### `swatches.shape`

The shape of each swatch. A code block can set its own on its fence line.

- Type: `'square' | 'rounded' | 'circle'`
- Default: `'rounded'`

### `swatches.size`

The width and height of each swatch, as a CSS length such as `10px` or `0.8em`.

- Type: `string`
- Default: `'0.8em'`

### `swatches.hover`

Tint the colour text in its own colour, and enlarge the swatch, when the mouse cursor is on it.

- Type: `boolean`
- Default: `true`

### `swatches.copy`

Copy the colour when the reader clicks it.

- Type: `boolean`
- Default: `true`

### `swatches.prose`

Also show swatches in the text of Markdown pages, and in inline code that is one colour. Named colours get a swatch only in inline code.

- Type: `boolean`
- Default: `false`

### `swatches.match`

Outside stylesheets, `value` shows a swatch only for a colour that looks like a value. `all` shows a swatch for every hex colour and colour function. A code block can set its own on its fence line.

- Type: `'value' | 'all'`
- Default: `'value'`

### `swatches.delimiters`

More text that can come before or after a colour that looks like a value, such as `|`. They add to the built-in delimiters.

- Type: `{ before?: string[]; after?: string[] }`
- Default: `{}`

### `swatches.byLanguage`

A `match` and `delimiters` for the blocks of each language. They replace the site settings for that language.

- Type: `Record<string, { match?: 'value' | 'all'; delimiters?: { before?: string[]; after?: string[] } }>`
- Default: `{}`

To show swatches for hex colours only, as circles, in CSS blocks only:

```js title="astro.config.mjs"
codeblocks({
  swatches: { formats: ['hex'], shape: 'circle', languages: ['css'] },
});
```

With `swatches.languages` set, add `swatches` to the fence line of a block of another language to turn on its swatches.

To find colours after and before a `|` in Mermaid blocks only, and every colour in `metro` blocks:

```js title="astro.config.mjs"
codeblocks({
  swatches: {
    byLanguage: {
      mermaid: { delimiters: { before: ['|'], after: ['|'] } },
      metro: { match: 'all' },
    },
  },
});
```

The `swatches.match` and `swatches.delimiters` options set the same for every language. A language in `swatches.byLanguage` uses its own settings in place of them.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## Limitations

- The plugin finds colours with patterns, not a CSS parser. A rare value can get a swatch that it does not need. Add `swatches=false` to that block.
- A colour that comes from a variable, such as `var(--accent)`, has no swatch.
- A swatch adds width to its line, so a column of values after it moves to the right.

## Related

- [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/): colour bracket pairs by depth, for dense lines with nested calls.
- [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting/): give inline code in the prose the syntax colours of the code blocks.