Focus

A code block often shows a whole file, but the text around it is about a few lines. Focus blurs and fades every other line, so readers find those lines at once. The other lines stay in the block, because readers need them for context.

Readers see

src/config.js

import { defineConfig } from './lib.js';

export default defineConfig({
  cache: {
    dir: '.cache',
    maxAge: 3600,
  },
  retries: 2,
  verbose: false,
});

You write

```js title="src/config.js" focus={4-7}
import { defineConfig } from './lib.js';

export default defineConfig({
  cache: {
    dir: '.cache',
    maxAge: 3600,
  },
  retries: 2,
  verbose: false,
});
```

Lines 4 to 7 are sharp, and the other lines are blurred. Hover over the block, or move keyboard focus into it, to make every line sharp. The copy button copies the whole file.

Syntax

Syntax	Where
focus={range}	Code block fence line
[!code focus]	Comment
[!code focus:N]	Comment
focus.style="blur", focus.style="dim"	Code block fence line

focus={range} takes a range, such as {2} or {1, 4-6}. [!code focus:N] focuses its own line and the next N-1 lines. You can use the attribute and directives in the same block.

Examples

Focus with a directive

A directive moves with its line when you edit the code. Use one when the block can change:

Output

app.py

import os

token = os.environ["API_TOKEN"]
url = "https://api.example.com/v1/items"

Source

```py title="app.py"
import os

token = os.environ["API_TOKEN"]  # [!code focus]
url = "https://api.example.com/v1/items"
```

Focus with a diff

Focus combines with the other line markers. Here the focused lines also show a change:

Output

server.ts

import { createServer } from 'node:http';

const port = 3000;
const port = Number(process.env.PORT ?? 3000);

createServer(handler).listen(port);

Source

```ts title="server.ts" focus={3-4}
import { createServer } from 'node:http';

const port = 3000; // [!code --]
const port = Number(process.env.PORT ?? 3000); // [!code ++]

createServer(handler).listen(port);
```

Behaviour

• The blur:
  • Lines outside the focus are blurred and faded. Focused lines look the same as in a block without focus.
  • If no line is in focus, the block is the same as a block without the plugin.
• Hover and keyboard:
  • When the reader hovers over the block, or moves keyboard focus into it, every line becomes clear. The change takes 250 ms.
  • The code area takes keyboard focus, so keyboard readers can see every line. Tab moves focus into it.
• Screen readers:
  • Screen readers read every line, because the blurred lines stay in the page.
• Copy:
  • The copy button copies every line, focused or not.
• Without JavaScript:
  • Focus needs no JavaScript in the browser.
• Motion:
  • When the reader’s system asks for reduced motion, the lines change without the transition.

Options

focus

Blurs the lines outside a focus range. Set it to false to turn the feature off. [!code focus] then stays in the code as written.

Type

false | object

Default

On

focus.style

Blur and fade the other lines, or only fade them. A code block can set its own on its fence line.

Type

'blur' | 'dim'

Default

'blur'

Blur makes the other lines hard to read for some readers. If your site does not need the blur, use the dim style:

astro.config.mjs

codeblocks({
  focus: { style: 'dim' },
});

To change the amount of blur, the opacity or the duration of the transition, use the codeblocksFocus style settings in styleOverrides:

ec.config.mjs

export default {
  styleOverrides: {
    codeblocksFocus: { blur: '2px', opacity: '0.6', transitionDuration: '150ms' },
  },
};

ConfigurationLearn how to set options for the whole site, or for a single code block.

Limitations

• Focus applies to whole lines. To point at a word on a line, use an inline callout.
• Every line becomes clear while the mouse cursor is over the block. Readers who use a touch screen see every line after they touch the block.

Related

• Line states: tint a line as an error, a warning or a note, with a message.
• Hidden lines: remove lines from view but keep them in the copied text.
• Scrollycoding: move the focus of one block as the reader scrolls through steps.