---
title: "Fill-in placeholders"
description: "Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code."
url: "https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders.md"
section: "Adapt to the reader"
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"
---

# Fill-in placeholders

> Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code.

Examples for an API often contain values that each reader has to change, such as `YOUR_TOKEN`. In a normal code block, readers copy the code and then edit it by hand. The `placeholder` attribute turns those values into fields. What a reader types fills every block on the site, and the copied code.

````md
```sh placeholder="YOUR_TOKEN,WORKSPACE_ID"
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/workspaces/WORKSPACE_ID/runs
```

```py placeholder="YOUR_TOKEN"
from example import Client

client = Client(token="YOUR_TOKEN")
```
````

Type a token into a `YOUR_TOKEN` field in one block, and the field in the other block shows it too. Each field is as wide as its text, and keeps the colour of the string it is in. The copy button copies the code with your values.

## Syntax

| Syntax | Where |
|---|---|
| `placeholder="<A>,<B>"` | Code block fence line |
| `placeholders.storage="local"`, `"session"` or `"none"` | Code block fence line |

The attribute lists the literal texts to turn into fields, separated by commas. Every match of each text in the block becomes a field. If one text contains another, the longer text wins where both match.

## Examples

### Values in a playground

This block combines fill-in placeholders with a playground button, to show that the playground gets the reader's value. Type a token, then click **Open in TS Playground**:

````md
```ts placeholder="YOUR_TOKEN" playground="typescript"
const response = await fetch('https://api.example.com/v1/runs', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(await response.json());
```
````

## Behaviour

- Fields:
  - A field shows its placeholder text until the reader types. Its accessible name is the placeholder text.
  - A field is as wide as its placeholder text or its value, whichever is longer.
- Typing:
  - Typing in a field updates every field with the same text on the page. Pages that load later show the value too.
  - Escape in a field clears its value, in every field with the same text.
  - Values stay in the reader's browser. The plugin never sends them anywhere.
- Copy, playgrounds and print:
  - The copy button copies the code with the reader's values. An empty field copies its placeholder text. A manual copy of a selection in the block copies the same way.
  - A [playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/) button opens the code with the reader's values.
  - A field prints as its text, without the border: the value if the reader typed one, or else the placeholder text.
- Warnings:
  - If a text in the attribute is not in the code, the build logs a warning.
- Without JavaScript:
  - Fields are plain inputs. They do not update each other, and the copy button copies the placeholder text.

**Danger:**
Tell readers where their values go. With the default `storage: 'local'`, the browser keeps the values after the reader closes the tab. On a shared computer, the next person can see them.

## Options

### `placeholders`

Turns placeholder text into input fields. Set it to `false` to turn the feature off.

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

### `placeholders.storage`

Where the browser keeps the values that readers type. A code block can set its own on its fence line.

- Type: `'local' | 'session' | 'none'`
- Default: `'local'`

`'local'` keeps values across visits. `'session'` keeps them until the reader closes the tab. `'none'` keeps them only while the page is open. For a site where readers type secrets, such as API tokens, use `'session'`:

```js title="astro.config.mjs"
codeblocks({
  placeholders: { storage: 'session' },
});
```

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

## Limitations

- A field matches literal text only. A text that also appears in a place that is not a placeholder becomes a field there too. Choose texts such as `YOUR_TOKEN` that appear nowhere else.
- A custom `url` playground gets the reader's values only if it puts the code in the URL with `encodeURIComponent()`. A custom `post` playground must put the code in a field as it is.

## Related

- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground/): open the code, with the reader's values, in an online playground.
- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): hide set-up lines, such as the line that reads a token from the environment.