The Diagram component

<Diagram> puts a diagram on any .mdx page or .astro file. The diagram loads when it scrolls into view, so a page with several diagrams stays fast. Until then the page holds a placeholder, because card heights are measured in the browser.

import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'

<Diagram name="checkout" />

Online store checkout

How a shopper's browser reaches the store, what the backend does with each request, and where things can go wrong. Click any box for details, or pick a scenario on the bar under the diagram and press play to watch a request travel through the system.

Everything in one picture. Letters on the edges match the interfaces table underneath.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

Pick a scenario to watch it play.

name is the folder name under diagrams/. If it does not match, the build stops with the names that exist: <Diagram name="chekout"> does not match a diagram. Available: checkout, payments, platform.

Props

Prop	Type	Meaning
`name`	string	Required. The folder under `diagrams/`.
`view`	string	The view to show first. Defaults to the diagram’s `defaults.view`, then its first view.
`scenario`	string	The scenario to select first. Defaults to the diagram’s `defaults.scenario`. It waits for the reader unless you add `autoplay`.
`mode`	`flow`, `sequence` or `story`	How the scenario is shown. Defaults to the scenario’s own `mode`, then the diagram’s `defaults.mode`, then `flow`.
`autoplay`	boolean	Play the scenario selected first as soon as the diagram is laid out.
`maxHeight`	number	The tallest the canvas may grow before it scrolls inside its frame, in pixels. Default 780.
`showTitle`	boolean	Show the diagram’s `title` above it.
`showDescription`	boolean	Show the diagram’s `description` above the first view.
`hash`	boolean	Keep the scenario, step and opened nodes in the address bar. Default `true`.
`sidebar`	boolean	Start with the panel over the picture (outline and views) open. By default it starts open when there is another view to choose, and in a widget wider than about 640 px. With `false` it starts folded to a button, and the reader can still open it. The scenarios and the player are on the bar under the picture whatever this says.
`subtitles`	boolean	Show the step’s title and description on the bar while the scenario plays. Default `true`.

A prop beats what the diagram file says under defaults, so the file can say how its diagram usually opens and a page can still choose otherwise.

See the props reference for the same list in one table.

Examples

<Diagram name="checkout" view="backend" />
<Diagram name="checkout" view="backend" scenario="place-order" />
<Diagram name="checkout" scenario="place-order" mode="sequence" />
<Diagram name="checkout" scenario="place-order" mode="story" />
<Diagram name="checkout" showDescription />

Open on a scenario, and play it

Everything in one picture. Letters on the edges match the interfaces table underneath.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

<Diagram name="checkout" scenario="payment-declined" autoplay hash={false} />

autoplay suits one diagram near the top of a page. Readers who ask their system for reduced motion are never autoplayed. Use hash={false} on embeds that should not change the address bar, such as a demo.

Open on a story

<Diagram name="platform" scenario="request-story" mode="story" />

Without mode, a scenario opens the way its own mode: says. With mode, the page decides. The reader can still switch with the buttons on the bar.

Show the description

showDescription puts the diagram’s description (Markdown, from the YAML) above the views. Examples pages use it to explain what to click.

The page around it

A diagram wants room. @the-package-labs/idocs-astro/starlight.css widens Starlight’s content column and holds ordinary text to a readable width, while diagrams use the full width. Add it to Starlight’s customCss:

starlight({
  customCss: ['@the-package-labs/idocs-astro/starlight.css'],
})

For a page that is only a diagram, hide the table of contents so the column is as wide as it can be:

---
title: Online store checkout
tableOfContents: false
---

Linking to a moment

When hash is on (the default), the address bar follows the selected scenario and step, so readers can share a link to what they are looking at. Opening such a link restores it. The format is #<diagram>=<scenario>[.<step>]. See playback.

You can write these links yourself in your prose:

[the declined card](/examples/checkout/#checkout=payment-declined.3)

In an Astro page

<Diagram> is an ordinary Astro component, so it works in .astro files as well:

---
import Diagram from '@the-package-labs/idocs-astro/Diagram.astro'
---

<Diagram name="shop" scenario="checkout" />

Do not add a client: directive to it. The component already loads its interactive part with client:visible.