---
title: "Focus"
description: "Blur the lines outside a range, so that readers look at the lines that you name first."
url: "https://ewels.github.io/starlight-codeblocks/features/focus/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/focus.md"
section: "Draw attention"
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"
---

# Focus

> Blur the lines outside a range, so that readers look at the lines that you name first.

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.

````md
```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](https://ewels.github.io/starlight-codeblocks/comment-notation/#line-numbers), 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:

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

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

```js title="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`:

```js title="ec.config.mjs"
export default {
  styleOverrides: {
    codeblocksFocus: { blur: '2px', opacity: '0.6', transitionDuration: '150ms' },
  },
};
```

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn 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](https://ewels.github.io/starlight-codeblocks/features/inline-callouts/).
- 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](https://ewels.github.io/starlight-codeblocks/features/line-states/): tint a line as an error, a warning or a note, with a message.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): remove lines from view but keep them in the copied text.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding/): move the focus of one block as the reader scrolls through steps.