<Live> turns one piece of code into a code block and its running result. The component reads the source back
from the rendered code block, so what runs is exactly what is shown (and, when editable, what the reader typed).
Every example on this page is a <Live>; the modules they load are in this site’s public/docs-assets/.
All props: Live and runners.
Write one
Section titled “Write one”In MDX, put a fenced code block inside <Live>, with a blank line after the opening tag and before the closing
one. MDX never touches the inside of a fence, so <script>, {braces} and template literals are safe.
import Live from 'astro-project-site/live';
<Live caption="A custom element from a module">
```html title="pill.html"<script type="module" src="/docs-assets/status-pill.js"></script><status-pill label="it runs"></status-pill>```
</Live><script type="module" src="/docs-assets/status-pill.js"></script><status-pill label="it runs"></status-pill>The fence’s title="…" and other Expressive Code meta work as usual. Serve the modules your examples load from
public/ or from a mirror of your library’s source (/lib/src/index.js).
In .astro files, or for code kept in a file, pass code instead (with lang and title):
---import Live from 'astro-project-site/live';import demo from '../demos/pill.html?raw';---<Live code={demo} title="pill.html" caption="Straight from a file" /><script type="module" src="/docs-assets/status-pill.js"></script><status-pill label="from the code prop" tone="purple"></status-pill>Inline mode (default): part of the page
Section titled “Inline mode (default): part of the page”mode="inline" renders into the page. Scripts run, classic and module, inline and external. Modules are
evaluated once per page (the browser’s module map), so two examples loading the same custom element do not
define it twice; external classic scripts are de-duplicated the same way.
Inline examples share the page: they can read and change it, a <style> applies to the whole page, and ids must
be unique. This one counts the headings of the page around it:
<p>This page has <strong id="h2-count">…</strong> sections.</p><script> document.getElementById('h2-count').textContent = document.querySelectorAll('.sl-markdown-content h2').length;</script>Iframe mode: isolated
Section titled “Iframe mode: isolated”mode="iframe" renders in a sandboxed iframe that sizes itself to its content. It receives Starlight’s colour and
font tokens (--sl-color-*, --sl-font) and follows the theme switch, so it still looks like the page. Use
head for styles or import maps, modules for module URLs, and base so relative URLs resolve against your
assets.
<script type="module" src="status-pill.js"></script><status-pill label="in an iframe"></status-pill><p><button id="more">Add a line</button> The frame grows with its content.</p><ul id="list"></ul><script> let n = 0; document.getElementById('more').onclick = () => { const li = document.createElement('li'); li.textContent = `line ${++n}`; document.getElementById('list').append(li); };</script>Errors in the iframe (exceptions, rejected promises, a script or stylesheet that fails to load) are shown under the preview.
Editable
Section titled “Editable”editable turns the code into a text area. Edits re-run the example after debounce ms (300 by default), the
copy button copies what was typed, and Reset restores the original. Tab inserts two spaces; Escape then Tab
leaves the editor. Editable HTML is best in an iframe, which starts from a clean document on every run.
<script type="module" src="status-pill.js"></script><status-pill label="edit this label" tone="orange"></status-pill><p>Try <code>tone="green"</code> or <code>tone="red"</code>.</p>Custom runners
Section titled “Custom runners”With runner="/url/of/module.js" the source is not HTML: it is handed to the module’s run(source, mount, ctx),
which renders it. That is how a library shows its own format (a chart spec, a config, a small language) running.
The code defaults to lang="json".
/** @type {import('astro-project-site').LiveRunner} */export function run(source, mount, ctx) { const spec = JSON.parse(source); // throw → the error shows under the preview const limit = Number(ctx.options.max ?? 12); // the `options` prop // …build an <svg> from spec.bars, coloured for ctx.theme, animated unless ctx.reducedMotion… mount.append(svg); ctx.status(`${n} bars`, 'ok'); // one line under the preview return () => animations.forEach((a) => a.cancel()); // cleanup before the next run}<Live runner="/docs-assets/runners/bar-chart.js" editable preview="side" options={{ max: 6 }} lazy>
```json title="downloads.json"{ "title": "Weekly downloads", "unit": "k", "bars": { "mon": 4, "tue": 7 } }```
</Live>{ "title": "Weekly downloads", "unit": "k", "bars": { "mon": 4, "tue": 7, "wed": 9, "thu": 6, "fri": 11 }}Add a sixth and seventh bar to see the max option’s warning; switch the theme to see it re-run with
ctx.theme. When run throws, the error is shown and the last good render stays:
{ "bars": { "ok": 3, "broken": "seven" } }The runner contract (LiveContext, when it re-runs, cleanup): Live and runners.
In iframe mode the runner module is loaded inside the iframe once; later edits only call run again.
Layout
Section titled “Layout”preview="above"(default),"below"or"side"(side by side from about 36rem of width, stacked below that).captionadds a caption with a#link. The anchor isid, else derived from the caption or title (#live-…), else from a hash of the source.heightis the preview’s minimum height (number = px), which avoids layout shift; in iframe mode also the frame’s height before it measures itself.lazystarts the example only when it scrolls near the viewport.
<p style="margin: 0">The preview can sit under the code, too.</p>Outside the docs
Section titled “Outside the docs”<Live> works on any BaseLayout page and in the landing hero (landing.hero.demo): theme.css supplies the
--sl-* tokens it uses outside Starlight. Its styles are scoped under live-example.