---
title: "Attributes"
description: "Every attribute that the plugin reads on the first line of a code block, with an example of each."
url: "https://ewels.github.io/starlight-codeblocks/reference/attributes/"
markdown: "https://ewels.github.io/starlight-codeblocks/reference/attributes.md"
section: "Reference"
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"
---

# Attributes

> Every attribute that the plugin reads on the first line of a code block, with an example of each.

An attribute goes on the fence line (the first line of the code block), after the language. A flag, such as `brackets`, is a name on its own. A value is in quotes, as in `playground="rust"`, or in braces for a range or a number, as in `focus={2-4}`. The [comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/) page explains how line numbers count in a range.

The attributes of Expressive Code, such as `title`, `frame`, `mark`, `ins`, `del`, `wrap` and `showLineNumbers`, keep working as before. The [Expressive Code docs](https://expressive-code.com/) describe them.

## `focus={range}`

Focuses the lines in the range. The other lines are blurred.

- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js focus={2}
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `error={range}`, `warning={range}`, `info={range}`, `success={range}`, `note={range}`, `warn={range}`

Marks the lines in the range with a line state. `note` is the same as `info`, and `warn` the same as `warning`. The attribute gives no message. Use a directive for a message.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js error={2}
const retries = 3
const delay = -1
const timeout = 5000
```
````

## `<state>={range}`

Marks the lines in the range with a custom line state from the `lineStates.states` option. This site defines `todo`.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js todo={2}
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `hidden={range}`

Hides the lines in the range behind a marker. The copy button still copies them.

- Feature: [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/)

````md
```js hidden={1-2}
import { readFile } from 'node:fs/promises';

const text = await readFile('config.json', 'utf8');
```
````

## `whitespace`, `whitespace="all"`

Shows spaces and tabs as faint glyphs. The flag shows leading whitespace only. `"all"` shows every space and tab.

- Feature: [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace/)

````md
```yaml whitespace
server:
  port: 8080
  hosts:
    - example.com
```
````

## `brackets`, `brackets=false`

Colours matching brackets by nesting depth. The `brackets.languages` option turns it on for whole languages, and `brackets=false` turns it off for one block.

- Feature: [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets/)

````md
```js brackets
const total = items.map((item) => item.price * (1 + tax));
```
````

## `swatches`, `swatches=false`

Shows a swatch before each CSS colour. Swatches are on for every block by default, and `swatches=false` turns them off for one block. With `swatches.languages` set, `swatches` turns them on for a block of another language.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```css swatches=false
.button {
  color: #ffffff;
  background: rebeccapurple;
}
```
````

## `swatches.shape="square"`, `swatches.shape="rounded"`, `swatches.shape="circle"`

Sets the shape of the swatches in the block. It overrides the `swatches.shape` option for the block.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```css swatches.shape="circle"
.badge {
  background: #2563eb;
}
```
````

## `swatches.match="all"`, `swatches.match="value"`

Sets which colours get a swatch in the block. `"all"` shows a swatch for every hex colour and colour function. It overrides the `swatches.match` option for the block.

- Feature: [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches/)

````md
```text swatches.match="all"
line: main | Main | #4caf50
```
````

## `icon="<name>"`, `icon=false`, `no-icon`

Sets the file icon before the title: an icon of the icon set, a Seti icon such as `react`, or a name from the `fileIcons.icons` option. `icon=false` and `no-icon` remove it.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```js title="vite.config.js" icon="vite"
export default {};
```
````

## `fileIcons.set="seti"`, `fileIcons.set="material"`, `fileIcons.set="vscode-icons"`, `fileIcons.set="catppuccin"`

Takes the file icon from vscode-icons, Material Icon Theme, Catppuccin or the Seti icons. It overrides the `fileIcons.set` option for the block. Material and Catppuccin need their `@iconify-json` package.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```json title="package.json" fileIcons.set="material"
{ "name": "my-site" }
```
````

## `fileIcons.style="plain"`, `fileIcons.style="tile"`

Shows the file icon alone, or on a square with rounded corners. It overrides the `fileIcons.style` option for the block.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```py title="app.py" fileIcons.style="tile"
print("Hello")
```
````

## `fileIcons.colour="<colour>"`

Sets the colour of the file icon, or of the square in the `tile` style, as a CSS colour such as `#3776ab`.

- Feature: [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons/)

````md
```py title="app.py" fileIcons.colour="#3776ab"
print("Hello")
```
````

## `wordDiff=false`

Turns off word-level diff for the block. Changed lines keep their whole-line tints.

- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

````md
```diff wordDiff=false
-const port = 3000
+const port = 8080
```
````

## `apiLinks=false`

Turns off API auto-linking for the block. Names stay plain text.

- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

````md
```py apiLinks=false
import json

config = json.loads('{"port": 8080}')
```
````

## `pydocsBase="<base>"`

Makes the Python adapter link names to the starlight-pydocs package at this base first, such as `1x/api/myproject` for an older version. Names that this package does not have link as usual.

- Feature: [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking/)

## `expandable`, `expandable={N}`, `expandable=false`

Shows the first lines of the block, with a button to show the rest. The flag shows the number of lines in the `expandable.lines` option. `{N}` shows `N` lines. `false` turns off the `expandable.auto` option for the block.

- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

````md
```yaml expandable={3}
name: Build
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
```
````

## `playground="<name>"`

Adds a button to the title bar that opens the code in a playground. The built-in names are `typescript` and `rust`.

- Feature: [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/)

````md
```ts playground="typescript"
const greet = (name: string) => 'Hello, ' + name;
```
````

## `id="<id>"`

Turns on line numbers, and makes each number a link to its line, as `#<id>-L<n>`.

- Feature: [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks/)

````md
```js id="server"
const host = 'localhost'
const port = 8080
```
````

## `placeholder="<A>,<B>"`

Turns each listed text in the block into an input field. The value that a reader types fills every block on the site.

- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)

````md
```sh placeholder="YOUR_TOKEN"
export API_TOKEN=YOUR_TOKEN
```
````

## `annotations="side"`

Shows the `[!annotate]` notes of the block in a column beside the code, on wide screens.

- Feature: [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/)

````md
```js annotations="side"
const port = 8080 // [!annotate] The port that the server listens on.
const host = 'localhost'
```
````

## `codeSide="right"`

With `annotations="side"`, puts the code in the right column and the notes in the left column. The default is `left`.

- Feature: [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations/)

## `footnotes="sticky"`, `footnotes="static"`

Keeps the list of footnotes at the bottom of the window while the block is on screen, or not. It overrides the `footnotes.sticky` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js footnotes="sticky"
// [!ref] The port that the server listens on.
const port = 8080
const host = 'localhost'
```
````

## `startNoteNumber={N}`

Numbers the annotations or footnotes of the block from `N`, not from 1, to continue the numbers of an earlier block.

- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js startNoteNumber={12}
const port = 8080 // [!annotate] The port that the server listens on.
```
````

## `label="<text>"`

Names a variant of a code tabs block. Its tab shows the label if the block has no title, and blocks with the same `sync` key match by label. It works only on a code block inside a `:::code-tabs` directive.

- Feature: [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs/)

## `step="<text>"`

Gives the label of a step in a `<CodeWalkthrough>` component. The title bar shows the label after the title.

- Feature: [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough/)

````md
```js title="server.js" step="Create the app"
import express from 'express';

const app = express();
```
````

## `runnable`

Adds a **Run code** button, which runs the code in the browser and shows the output under the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable
print(sum([1, 2, 3]))
```
````

## `runnable.label="<text>"`

The text of the button of a `runnable` block. It overrides the `runnable.label` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable runnable.label="Try it"
print(sum([1, 2, 3]))
```
````

## `runnable.againLabel="<text>"`

The text of the button after the first run. It overrides the `runnable.againLabel` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.timeout=<ms>`

Milliseconds before a run stops. It overrides the `runnable.timeout` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.packages="<name> <name>"`

Python packages to install from Pyodide or PyPI before the code runs, separated by spaces. Use it when the package name is not the import name.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```py runnable runnable.packages="python-slugify"
from slugify import slugify
print(slugify("Hello, World!"))
```
````

## `runnable.button="below"`, `runnable.button="title"`, `runnable.button="both"`

Puts the button under the block, in the title bar, or both. It overrides the `runnable.button` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `runnable.output="<text>"`

Output that the button prints instead of running the code, a line at a time. `\n` starts a new line. The block needs no runtime.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

````md
```sh runnable.output="Downloading…\nDone."
nextflow run hello
```
````

## `runnable.outputDelay=<ms>`

Milliseconds between the lines of `runnable.output`. `0` prints them all at once. It overrides the `runnable.outputDelay` option for the block.

- Feature: [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code/)

## `focus.style="blur"`, `focus.style="dim"`

Blurs and fades the lines outside the focus, or only fades them. It overrides the `focus.style` option for the block.

- Feature: [Focus](https://ewels.github.io/starlight-codeblocks/features/focus/)

````md
```js focus={2} focus.style="dim"
const host = 'localhost'
const port = 8080
const debug = false
```
````

## `lineStates.prefix=false`, `lineStates.prefix=true`

Shows the name of the state before each message, or not. It overrides the `lineStates.prefix` option for the block.

- Feature: [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states/)

````md
```js lineStates.prefix=false
const retries = -1 // [!code error] Must be 0 or more
```
````

## `shellCopy.prompts="<text>"`

A prompt that starts a command in a terminal block, such as `shellCopy.prompts="% "`. Repeat it for more prompts. It replaces the `shellCopy.prompts` option for the block.

- Feature: [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy/)

````md
```sh shellCopy.prompts="% "
% npm run build
Built in 2.1 s
```
````

## `wordDiff.minSimilarity=<0-1>`

How similar a removed and an added line must be for word-level diff to compare them. It overrides the `wordDiff.minSimilarity` option for the block.

- Feature: [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff/)

## `footnotes.sticky=false`, `footnotes.sticky=true`

Keeps the list of footnotes in view while the block is on screen, or not. It overrides the `footnotes.sticky` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

## `footnotes.style="filled"`, `footnotes.style="outline"`

Draws the badges filled in the accent colour, or outlined in the magenta of the theme. It overrides the `footnotes.style` option for the block.

- Feature: [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes/)

````md
```js footnotes.style="filled"
// [!ref] Read from the environment.
const port = process.env.PORT
```
````

## `annotations.style="filled"`, `annotations.style="outline"`

Draws the markers filled in the accent colour, or outlined in the magenta of the theme. It overrides the `annotations.style` option for the block.

- Feature: [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations/)

````md
```js annotations.style="outline"
const port = 8080 // [!annotate] The default port.
```
````

## `expandable.lines=<N>`

The lines that the block shows before it expands, when it is expandable. It overrides the `expandable.lines` option for the block.

- Feature: [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/)

## `placeholders.storage="local"`, `placeholders.storage="session"`, `placeholders.storage="none"`

Where the browser keeps the values that readers type into the fields of the block. It overrides the `placeholders.storage` option for the block.

- Feature: [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/)