Colour swatches

View as Markdown Open in Claude Open in ChatGPT

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.

Readers see

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

You write

```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:

Output
Source

: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;
}

```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:

Output
Source

.tag { background: #22c55e; }

.tag { background: #22c55e; }

.tag { background: #22c55e; }

```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:

Output
Source

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

```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:

Output
Source

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

```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:

Output
Source

%%metro line: main | Main | #4caf50
%%metro line: qc | Quality Control | #2196f3 | dashed

```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:

Output
Source

:root { --accent: #ff5f1f; }

```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:

Output
Source

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

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:

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:

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.

ConfigurationLearn 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.

Colourised brackets: colour bracket pairs by depth, for dense lines with nested calls.
Inline code highlighting: give inline code in the prose the syntax colours of the code blocks.

Colour swatches

Syntax

Examples

Every kind of colour

Swatch shapes

Colours with transparency

Colours in other languages

Every colour in a block

Turn off swatches for one block

Colours in the prose

Behaviour

Options

swatches

swatches.languages

swatches.formats

swatches.shape

swatches.size

swatches.hover

swatches.copy

swatches.prose

swatches.match

swatches.delimiters

swatches.byLanguage