---
title: "Colourised brackets"
description: "Colour matching brackets by nesting depth, so a dense line of code stays readable."
url: "https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/colourised-brackets.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"
---

# Colourised brackets

> Colour matching brackets by nesting depth, so a dense line of code stays readable.

A line with several levels of nested brackets is hard to scan: every `(`, `[` and `{` looks the same. The `brackets` attribute colours each bracket by how deep it is nested, cycling through three colours. A reader can then follow a pair by its colour.

````md
```js brackets
const title = document.title;
const slug = encodeURIComponent(
  kebab(trim(title.toLowerCase()))
);
```
````

The colour cycles every three levels, so the outermost call and the innermost call share a colour. Hover over a bracket to outline it and its partner, so you can tell the two pairs apart even when their colour repeats.

## Syntax

| Syntax | Where |
|---|---|
| `brackets` | Code block fence line |
| `brackets=false` | Code block fence line |

## Examples

### Brackets inside a string

Brackets inside a string stay the normal string colour:

````md
```js brackets
const pattern = "(group)";
```
````

## Behaviour

- Colours:
  - `()`, `[]` and `{}` cycle through three colours by nesting depth.
  - Brackets inside a string or a comment keep the normal syntax colour, so they do not compete with the real structure of the code.
  - A bracket with no partner, such as one from an incomplete example, keeps its normal colour.
- Matching pairs:
  - Hovering over a bracket outlines it and its matching partner with a solid line. The pair then stands out by shape, not only by colour.
  - Readers who use caret browsing (F7 in most browsers) get the same outline when the caret is on a bracket.
- Without JavaScript:
  - The colours work without JavaScript. The outline needs JavaScript, and does nothing without it.

## Options

### `brackets`

Colours matching brackets by nesting depth. Set it to `false` to turn the feature off.

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

### `brackets.languages`

Languages that get colourised brackets in every block.

- Type: `string[]`
- Default: `[]`

A site that writes a lot of deeply nested JavaScript or JSON can turn colourised brackets on for those languages by default:

```js title="astro.config.mjs"
codeblocks({
  brackets: { languages: ['js', 'json'] },
});
```

Each name also covers the other names of its language, so `js` also turns on the colours in `javascript` and `mjs` blocks.

To turn the colours off for one block of those languages, add `brackets=false` to its fence line. The fence line is the first line of the code block, with the language.

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

## Limitations

- On a short line with only one level of nesting, the colours add little. Use the attribute for lines that are hard to scan, or turn it on for a whole language with `brackets.languages` when it is usually dense.
- The plugin finds strings and comments with the comment syntax of the block's language, not a full parser. A language with unusual string syntax can colour a bracket that is inside a string.

## Related

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/): blur everything except the lines with the brackets you are explaining.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the comment syntax map that colourised brackets reads to skip comments.