docs

Full documentation content.

<page path="/getting-started/introduction" title="pmndrs/docs"><![CDATA[URL: /getting-started/introduction
Description: Documentation generator for `pmndrs/*` projects.

# pmndrs/docs

Documentation generator for `pmndrs/*` projects.

[npm @pmndrs/docs](https://www.npmjs.com/package/@pmndrs/docs) [storybook](https://main--6977e41687a50b30c4349650.chromatic.com) [chromatic storybook](https://www.chromatic.com/library?appId=6977e41687a50b30c4349650\&branch=main)

A static MDX documentation generator, with a GitHub [reusable workflow](/github-actions/introduction). It is primarily used for some `pmndrs/*` projects, but will work for anyone.

![Gutenberg lithography](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/getting-started/gutenberg.jpg)

[Those projects](https://github.com/search?q=%22uses%3A+pmndrs%2Fdocs%2F.github%2Fworkflows%2Fbuild.yml%22+language%3AYAML\&type=code\&l=YAML) are known to be using this generator.

## INSTALL

### Clone the repository

```sh
$ git clone https://github.com/pmndrs/docs.git
$ cd docs
```

### Use the right Node version

With [nvm](https://github.com/nvm-sh/nvm), which reads the repository's `.nvmrc`:

```sh
$ nvm install
$ nvm use
$ node -v # make sure your version satisfies package.json#engines.node
```

nb: if you want this node version to be your default nvm's one: `nvm alias default node`

### Install the dependencies

```sh
$ pnpm install
```

## Configuration

Environment variables configure the website. For MDX extensions, add `docs.config.ts` in the current working directory: `components` registers React components and `scope` exposes named data. Both fields are optional. See [Custom components and data](/authoring/custom-components) for the typed configuration and a live example.

> \[!IMPORTANT]
>
> Variables default to `""` (empty) unless a fallback is documented below.

| var                         | description                                                                                                                                                                                                                                                     | example                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `MDX`\*                     | Path to `*.mdx` folder NB: can be relative or absolute                                                                                                                                                                                                          | `docs` or `~/code/myproject/documentation`                                                       |
| `DOCS_CONFIG`               | Path to the component and data configuration, relative to the current working directory or absolute. Unset: look for `docs.config.ts` there; no file keeps the built-in renderer. CLI: `--config` overrides this variable.                                      | `config/docs.config.ts`                                                                          |
| `NEXT_PUBLIC_LIBNAME`\*     | Library name                                                                                                                                                                                                                                                    | `React Three Fiber`                                                                              |
| `NEXT_PUBLIC_LIBNAME_SHORT` | Library short name                                                                                                                                                                                                                                              | `r3f`                                                                                            |
| `BASE_PATH`                 | Base path for the final URL                                                                                                                                                                                                                                     | `/react-three-fiber`                                                                             |
| `HOME_REDIRECT`             | Where the home should redirect                                                                                                                                                                                                                                  | `/getting-started/introduction`                                                                  |
| `MDX_BASEURL`               | Base URL for inlining relative images, or a path (e.g. `/react-three-fiber`) for root-relative ones                                                                                                                                                             | `http://localhost:60141`or `https://github.com/pmndrs/react-three-fiber/raw/master/docs`         |
| `SOURCECODE_BASEURL`        | Base URL for `sourcecode:` code path, and for relative links to repository files out of `MDX`: the tree of the repository root (as the reusable workflow sets it)                                                                                               | `https://github.com/pmndrs/react-three-fiber/tree/main`                                          |
| `EDIT_BASEURL`              | Base URL for displaying "Edit this page" URLs                                                                                                                                                                                                                   | `https://github.com/pmndrs/react-three-fiber/edit/master/docs`                                   |
| `NEXT_PUBLIC_URL`           | Final URL of the published website                                                                                                                                                                                                                              | `https://pmndrs.github.io/react-three-fiber`                                                     |
| `ICON`                      | Emoji or image to use as (fav)icon (path local to `MDX`) NB: also published at `/icon.svg`, which the libraries menu of the other pmndrs docs sites shows                                                                                                       | `🇨🇭` or `/icon.png` or `/favicon.ico`                                                          |
| `LOGO`                      | Logo src/path (either FQURL or local to `MDX` path)                                                                                                                                                                                                             | `/logo.png` or `https://worldvectorlogo.com/r3f.png`                                             |
| `GITHUB`                    | Github URL (its star count shows next to the header link)                                                                                                                                                                                                       | `https://github.com/pmndrs/react-three-fiber`                                                    |
| `DISCORD`                   | Discord URL                                                                                                                                                                                                                                                     | `https://discord.com/channels/740090768164651008/740093168770613279`                             |
| `SPONSOR_CARD`              | "Sponsor Poimandres" card under the table of contents, on unless `false` -- for a site that is not a pmndrs library                                                                                                                                             | `false`                                                                                          |
| `LIBS_MENU`                 | Menu of the pmndrs libraries behind the site name in the header, on unless `false`: the name is then a plain link home                                                                                                                                          | `false`                                                                                          |
| `THEME_PRIMARY`             | Primary accent color (unset: the pmndrs lime `#CAF543`)                                                                                                                                                                                                         | `#323e48`                                                                                        |
| `THEME_SCHEME`              | Theme scheme, moot while color match is on (see `THEME_COLOR_MATCH`)                                                                                                                                                                                            | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` |
| `THEME_CONTRAST`            | Theme contrast -- value between -1 and 1                                                                                                                                                                                                                        | `0` or `-1` or `1` or `-.6`                                                                      |
| `THEME_NOTE`                | "note" color                                                                                                                                                                                                                                                    | `#1f6feb`                                                                                        |
| `THEME_TIP`                 | "tip" color                                                                                                                                                                                                                                                     | `#238636`                                                                                        |
| `THEME_IMPORTANT`           | "important" color                                                                                                                                                                                                                                               | `#8957e5`                                                                                        |
| `THEME_WARNING`             | "warning" color                                                                                                                                                                                                                                                 | `#d29922`                                                                                        |
| `THEME_CAUTION`             | "caution" color                                                                                                                                                                                                                                                 | `#da3633`                                                                                        |
| `THEME_CUSTOM_COLORS`       | Custom colors of the theme, `name:hex[:blend]` comma-separated -- each a role, `<Color role="brand" />`, `:blend` harmonizing it with the primary                                                                                                               | `brand:#ff2d95:blend,status:#17b26a`                                                             |
| `THEME_COLOR_MATCH`         | Each core and custom color rendered true to its own input (Material Theme Builder's "Color match"), on unless `false`: it takes precedence over `THEME_SCHEME`, readers can toggle it from the sidebar, and the scheme toggle is hidden while color match is on | `true` or `false`                                                                                |
| `THEME_SECONDARY`           | Secondary color, instead of the one derived from the primary                                                                                                                                                                                                    | `#B03A3A`                                                                                        |
| `THEME_TERTIARY`            | Tertiary color, instead of the one derived from the primary                                                                                                                                                                                                     | `#7D5260`                                                                                        |
| `THEME_NEUTRAL`             | Neutral color (the surfaces), instead of the pmndrs warm grey `#c1b793`                                                                                                                                                                                         | `#c1b793`                                                                                        |
| `THEME_NEUTRAL_VARIANT`     | Neutral variant color (the tinted surfaces, outlines), instead of the pmndrs `#495720`                                                                                                                                                                          | `#495720`                                                                                        |
| `THEME_ERROR`               | Error color, instead of the pmndrs red `#FF4980`                                                                                                                                                                                                                | `#FF4980`                                                                                        |
| `THEME_STORYBOOK`           | "storybook" color                                                                                                                                                                                                                                               | `#ff4785`                                                                                        |
| `THEME_NPM`                 | "npm" color                                                                                                                                                                                                                                                     | `#cb3837`                                                                                        |
| `THEME_CHROMATIC`           | "chromatic" color                                                                                                                                                                                                                                               | `#fc521f`                                                                                        |
| `CONTRIBUTORS_PAT`          | GitHub token for contributors API and the header star count (see: <https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators>)                                                                            | `ghp_1234567890`                                                                                 |
| `LIB_VERSION`               | Version label in the sidebar footer (default: `git describe --tags`)                                                                                                                                                                                            | `v1.2.3`                                                                                         |
| `TAG_MATCH`                 | Tags the version label is read from (`git describe --match`)                                                                                                                                                                                                    | `v*.*.*`                                                                                         |
| `VERSION_URL_TEMPLATE`      | URL of a branch deployment; enables the [version switcher](#version-switcher)                                                                                                                                                                                   | `https://mylib-git-{branch:vercel}-myteam.vercel.app`                                            |
| `VERSION_PRODUCTION_BRANCH` | Production branch (default: `main`)                                                                                                                                                                                                                             | `master`                                                                                         |
| `VERSION_PRODUCTION_URL`    | Production branch URL (default: `NEXT_PUBLIC_URL`)                                                                                                                                                                                                              | `https://docs.pmnd.rs`                                                                           |
| `VERSION_BRANCHES`          | Regex of the branches the switcher offers                                                                                                                                                                                                                       | `^(main\|next\|v\d+)$`                                                                           |
| `VERSION_BRANCHES_LIST`     | Branches the switcher offers, instead of the remote's                                                                                                                                                                                                           | `main,next,v9`                                                                                   |

\* Required

Readers can re-seed `THEME_PRIMARY`, `THEME_SCHEME`, `THEME_CONTRAST` and `THEME_COLOR_MATCH` from the theme controls in the sidebar. An overridden control is outlined, and a double-click (or Delete) brings the site's value back.

`MDX_BASEURL`

Given a `advanced/introduction.mdx` file in the `MDX` folder:

```md title="advanced/introduction.mdx"
![](dog.png)
```

becomes (for a `MDX_BASEURL=http://localhost:60141` value):

```md
![](http://localhost:60141/advanced/dog.png)
```

`http://localhost:60141` being the `MDX` folder served.

> \[!TIP] When deployed on GitHub Pages, `MDX_BASEURL` will typically value something like `https://github.com/pmndrs/uikit/raw/main/docs`, thanks to [`build.yml`](https://github.com/pmndrs/docs/tree/dependabot/github_actions/pnpm/action-setup-6/.github/workflows/build.yml) rule.

`MDX_BASEURL` can also be a path only, root-relative, such as `/react-three-fiber` (or `/` for a site served at the root of its domain): the `MDX` folder then has to be served at that path, on the same host as the website. URLs then come out root-relative too:

```md
![](/react-three-fiber/advanced/dog.png)
```

so they follow the website onto any host it answers on (e.g. both the deployment and the branch URL of a Vercel preview), where an absolute URL would point to one host only.

> \[!NOTE] With a path, the `image` frontmatter (`og:image`) is made absolute against the origin of `NEXT_PUBLIC_URL`, when set, since social images need an absolute URL.

`THEME_*`

We implement [m3 design system](https://m3.material.io/styles/color/system/overview), using [material-theme-builder](https://github.com/abernier/material-theme-builder).

[material-theme-builder color scheme](https://main--695eb517cb602e59b4cc045c.chromatic.com/iframe.html?id=mtb--st-1\&viewMode=story)

This is an embed iframe of [material-theme-builder's `<Mtb>` story](https://main--695eb517cb602e59b4cc045c.chromatic.com/?path=/story/mtb--st-1).

> \[!NOTE]
>
> - [Material Color](https://www.youtube.com/playlist?list=PLsoLz-E4Os4WWkrvRuQ7BJuVF-WfOyfWT) for more information
> - The defaults are [pmndrs/design-system](https://github.com/pmndrs/design-system)'s palette: the lime `#CAF543` under color match, a warm grey neutral, and seven colors every site gets as custom colors, `lime`, `teal`, `cyan`, `purple`, `red`, `orange` and `yellow` (`<Color role="teal" />`).
> - `THEME_PRIMARY` is the seed: the secondary and tertiary colors are derived from it, unless the site gives its own (`THEME_SECONDARY`, `THEME_TERTIARY`). The neutral, neutral variant and error colors are the pmndrs ones, unless the site gives its own (`THEME_NEUTRAL`, `THEME_NEUTRAL_VARIANT`, `THEME_ERROR`).
> - `THEME_COLOR_MATCH` (on unless `"false"`) is [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/)'s "Color match - Stay true to my color inputs": each core and custom color keeps its input's chroma instead of being toned down to the scheme's, so `THEME_SCHEME` is ignored and the scheme toggle is hidden while color match is on. Readers can toggle color match from the sidebar. A custom color with `:blend` is still harmonized first.

`VERSION_*`, `LIB_VERSION`, `TAG_MATCH`

- Label: `git describe --tags` (eg. `v10.7.9`, `v10.7.9-3-ga1b2c3d`), or `<branch>@<shortsha>` without tags. `LIB_VERSION` overrides it.
- `TAG_MATCH` narrows the tags:

| repo tags                  | `TAG_MATCH` |
| -------------------------- | ----------- |
| `v10.7.9`, `v10`           | `v*.*.*`    |
| `leva@0.10.1`, `other@1.0` | `leva@*`    |

- `VERSION_URL_TEMPLATE` enables the switcher: the label lists the branches, each leading to the same page on its deployment. Full public URL (base path included), with a placeholder:

| placeholder       | `feat/Dark_mode` becomes | for                    | example                                               |
| ----------------- | ------------------------ | ---------------------- | ----------------------------------------------------- |
| `{branch}`        | `feat-dark-mode`         | URLs you create        | `https://docs-git-{branch}-pmndrs.vercel.app`         |
| `{branch:vercel}` | `feat-darkmode`          | Vercel Git integration | `https://mylib-git-{branch:vercel}-myteam.vercel.app` |
| `{branch:raw}`    | `feat%2FDark_mode`       | a path or query string | `https://example.com/preview?branch={branch:raw}`     |

- A hostname label holds 63 characters at most. When a long branch would overflow it, `{branch:vercel}` follows Vercel's own truncation, and `{branch}` keeps its slug's first `63 - (rest of the label) - 7` characters, drops a trailing `-`, and appends `-` and the first 6 hex characters of the branch name's SHA-256 (`printf %s "$branch" | sha256sum | cut -c1-6`): eg. `claude/pages-shadcn-tailwind-prep-98d23c` in `https://design-system-git-{branch}-pmndrs.vercel.app` becomes `design-system-git-claude-pages-shadcn-tailwind-pr-2675d4-pmndrs`. Outside the hostname, `{branch}` is never cut. To alias a deployment there, `pmndrs-docs version-url` prints the URL (`--hostname`: the hostname alone), or see the reusable workflow's [`version_hostname` output](/github-actions/introduction#version-switcher).

- `VERSION_PRODUCTION_BRANCH` leads to `VERSION_PRODUCTION_URL`; every other branch shows a banner linking to production.

- Branches: the remote's, minus `dependabot/`, `renovate/`, `changeset-release/`. `VERSION_BRANCHES` replaces that filter, `VERSION_BRANCHES_LIST` the whole list. Read at build time.

> \[!IMPORTANT]
>
> - The per-branch URLs are yours to create: Vercel's Git integration does, `vercel deploy` does not (`vercel alias set`, see [`ci.yml`](https://github.com/pmndrs/docs/blob/main/.github/workflows/ci.yml)).
> - Git needs full history and tags (`fetch-depth: 0`).

## Usage

### dev

Run [`dev.sh`](https://github.com/pmndrs/docs/blob/main/dev.sh). The site listens on `PORT` (default `3000`), the MDX folder on any free port, so several checkouts can run side by side:

```sh
$ ./dev.sh
```

which is:

```sh title="dev.sh" collapsible
#!/bin/sh

trap 'kill -9 0' SIGINT

export PORT=${PORT:-3000}
export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

export MDX=docs
export NEXT_PUBLIC_LIBNAME="docs"
export NEXT_PUBLIC_LIBNAME_SHORT="docs"
export BASE_PATH=
export HOME_REDIRECT=
export MDX_BASEURL=http://localhost:$_PORT
export SOURCECODE_BASEURL="vscode://file$(pwd)"
export EDIT_BASEURL="vscode://file$(pwd)/docs"
export NEXT_PUBLIC_URL=
export ICON=
export LOGO=gutenberg.jpg
export GITHUB=https://github.com/pmndrs/docs
export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
export CONTRIBUTORS_PAT=

npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

pnpm run dev &

wait
```

Then go to: <http://localhost:3000>

When running the engine against another repository, set both `MDX` and `DOCS_CONFIG`; the configuration is discovered from the working directory, not the MDX folder:

```sh
MDX=/path/to/library/docs DOCS_CONFIG=/path/to/library/docs.config.ts pnpm dev
```

> \[!TIP] If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries.

### build

Run [`start.sh`](https://github.com/pmndrs/docs/blob/main/start.sh), same ports:

```sh
$ ./start.sh
```

which is:

```sh title="start.sh" collapsible
#!/bin/sh

trap 'kill -9 0' SIGINT

rm -rf out

export PORT=${PORT:-3000}
export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

export MDX=docs
export NEXT_PUBLIC_LIBNAME="docs"
export NEXT_PUBLIC_LIBNAME_SHORT="docs"
export BASE_PATH=
export HOME_REDIRECT=
export MDX_BASEURL=http://localhost:$_PORT
export SOURCECODE_BASEURL=
export EDIT_BASEURL=
export NEXT_PUBLIC_URL=
export ICON=
export LOGO=gutenberg.jpg
export GITHUB=https://github.com/pmndrs/docs
export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
export CONTRIBUTORS_PAT=

# The static export is the CLI's, built from this checkout: the same one the package publishes
pnpm run build:cli || exit 1
node bin/pmndrs-docs.mjs build $MDX out --format website || exit 1

npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

npx serve out -p $PORT &

wait
```

<http://localhost:3000>

### CLI

The published CLI builds without cloning the engine. If your custom components import packages, install those dependencies in your repository first:

```sh
$ cd ~/code/pmndrs/react-three-fiber
$ curl -sL https://raw.githubusercontent.com/pmndrs/docs/refs/heads/main/preview.sh | \
  MDX="docs" \
  NEXT_PUBLIC_LIBNAME="React Three Fiber" \
  HOME_REDIRECT="/getting-started/introduction" \
  ICON="🇨🇭" \
  sh
```

which is:

```sh title="preview.sh" collapsible
#!/bin/sh

main() {
  trap 'kill -9 0' SIGINT

  export PORT="${PORT:-3000}"
  export _PORT="${_PORT:-$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')}"
  export VERSION="${VERSION:-latest}"

  export MDX="${MDX:-docs}"
  export NEXT_PUBLIC_LIBNAME="${NEXT_PUBLIC_LIBNAME:-docs}"
  # Relative assets resolve against the MDX folder, served below on the same port
  export MDX_BASEURL="${MDX_BASEURL:-http://localhost:$_PORT}"

  rm -rf "$MDX/out"

  # Every other option is read straight from the environment — same process, nothing to forward
  npx -y "@pmndrs/docs@$VERSION" build "$MDX" "$MDX/out" --format website || exit 1

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx -y serve "$MDX/out" -p $PORT &

  wait
}

main
```

Any [configuration](#configuration) variable goes in the same way; `VERSION` picks a published version of the CLI.

Then go to: <http://localhost:3000>

`npx @pmndrs/docs@latest build --help` lists the CLI flags, including `--config` for a configuration outside the repository root.

Both `--format website` and `--format fragment` use the same Next.js build and static export. Fragments contain only the compiled document: no layout, stylesheet or script. The CLI copies assets alongside folder fragments and preserves static Mermaid and Sandpack content.

```sh
$ npx @pmndrs/docs@latest build page.mdx
$ cat page.mdx | npx @pmndrs/docs@latest build
```

A single file or stdin writes HTML to stdout and build logs to stderr. These inputs also run a full Next.js build. Consumer components and data use the same `docs.config.ts` as the website.

### read

The same CLI reads every pmndrs library in the terminal:

```sh
$ npx @pmndrs/docs                                 # every library, every page
$ npx @pmndrs/docs drei                            # one library
$ npx @pmndrs/docs drei/performances/instances     # one page
$ npx @pmndrs/docs search instanced mesh           # one result per line, on stdout
```

`↑↓` moves in the focused pane, `⇥` switches pane, `←→` changes library, `/` searches, `o` opens the page in a browser, `q` quits. `npx @pmndrs/docs browse --help` lists every key.

`search` prints `{lib} {path} - {title}` and exits 1 when nothing matches; `--in drei` narrows it to one library, `--in drei/performances/instances` to the matching lines of one page.

Pages come from each library's `llms-full.txt`, cached for an hour (`--refresh` refetches). Piped, a page goes to stdout: `npx @pmndrs/docs drei/performances/instances | glow`.

## Agents

`llms.txt` dumps and the pmndrs MCP server moved to their own page: [Agents](/agents/introduction).
]]></page>
<page path="/authoring/introduction" title="Authoring"><![CDATA[URL: /authoring/introduction
Description: How to write documentation

# Authoring

How to write documentation

This is a guide on how to write documentation. We support all [GFM](https://github.github.com/gfm/) syntax, plus some custom components that are described here.

## Keypoints

- [Front matter](#frontmatter) metadatas
- Custom [markdown](#markdown) components

In your `MDX` folder, create any `path/to/my-document.mdx`:

```md title="path/to/my-document.mdx"
---
title: My Document
description: Lorem ipsum...
nav: 0
image: dog.png
sourcecode: to/my-document.mdx
---

MARKDOWN
```

## Frontmatter

Any key is optional.

- `title`: if not provided, last part of the path is used: `my document`

- `description`

- `sourcecode`: relative path to the source-code file

- `edit`: absolute URL of the "Edit this page" link, instead of the file's path under [`EDIT_BASEURL`](/getting-started/introduction#configuration) -- for a page generated from a source elsewhere, eg: `https://github.com/me/mylib/edit/main/README.md`

- `image`:

  - relative (to the md file) or absolute path, eg: `dog.png`, `./dog.png`, `../../dog.png`, `/dog.png` or `https://animals.com/dog.png`
  - will be used as metadata image if provided

- `nav`: order in the navigation (on the same level)

> \[!TIP]
>
> `title` and `description` support markdown:
>
> ```yaml
> ---
> title: "`Intro` component"
> description: Introduction component for **documentation** pages with `code` and [links](#test)
> ---
> ```
>
> ⚠️ If starting with backtick, eg ``title: "`Intro` component"`` wrap in quotes!

## MARKDOWN

Worth mentioning, you can use **standard HTML**, with [tailwind](https://tailwindcss.com) support:

```md
<div>
  <iframe src="https://drei.pmnd.rs/iframe.html?globals=&args=&id=staging-accumulativeshadows--accumulative-shadow-st&viewMode=story" 
    className="w-full h-60 rounded-lg"
  />
  <p className="mt-1 text-xs text-on-surface-variant">This is an embed iframe of [Drei's `<AccumulativeShadows>` story](https://drei.pmnd.rs/?path=/docs/staging-accumulativeshadows--docs).</p>
</div>
```

result:

This is an embed iframe of [Drei's `<AccumulativeShadows>` story](https://drei.pmnd.rs/?path=/docs/staging-accumulativeshadows--docs).

> \[!TIP]
>
> We use [material-theme-builder](https://github.com/abernier/material-theme-builder) colors, eg: `text-on-surface-variant` above

Plus:

- any [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax.
- all exported [`components/mdx/index.tsx`](https://github.com/pmndrs/docs/tree/dependabot/github_actions/pnpm/action-setup-6/src/components/mdx/index.tsx) MDX components.

A relative link to a file of the repository out of the `MDX` folder, like the one above, links to that file on GitHub, on the branch deployed, under [`SOURCECODE_BASEURL`](/getting-started/introduction#configuration:~:text=SOURCECODE_BASEURL). Its path starts from the repository root: the nearest folder with a `.git`, else (built without `.git`) the nearest with a `package.json`, which in a monorepo may be a workspace package. It works on GitHub as is. A link staying in the `MDX` folder, to another page or an asset, is left as is.

See the following pages for detailed documentation on each custom component.

To register your own React components and shared data for MDX pages, see [Custom components and data](custom-components).
]]></page>
<page path="/authoring/intro" title="`Intro`"><![CDATA[URL: /authoring/intro
Description: Introduction component for **documentation** pages with `code` and [links](#test)

# `Intro`

Introduction component for **documentation** pages with `code` and [links](#test)

Prominent introduction with rich markdown support.

Use at the top of the document, just after the frontmatter.

```md
<Intro>
  This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc.
  
  Multiple paragraphs are also possible, or anything.
</Intro>
```

result:

This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc.

Multiple paragraphs are also possible, or anything.
]]></page>
<page path="/authoring/keypoints" title="`Keypoints`"><![CDATA[URL: /authoring/keypoints
Description: Keypoints component for highlighting main article topics

# `Keypoints`

Keypoints component for highlighting main article topics

[storybook](https://main--6977e41687a50b30c4349650.chromatic.com/?path=/docs/keypoints--docs)

Highlights key takeaways as a visually distinct bulleted list.

Can be used after `Intro`, to list main points the article covers: one bullet per `KeypointsItem`.

`Keypoints` composes a shadcn `Card`, while keeping a native section, heading and bulleted list. Its MDX API stays the same.

To install the standalone block in a shadcn project:

```sh
pnpm dlx shadcn@latest add pmndrs/docs/keypoints
```

The registry installs `card` using your project's shadcn base and preset. It also resolves an explicit, release-tagged `pmndrs/design-system/theme` dependency, bringing the design system's palette and mono font. Card alone does not install that theme, and Keypoints needs no custom surface utility.

```md
<Keypoints title="What you'll learn">
  <KeypointsItem>First item</KeypointsItem>
  <KeypointsItem>Second **item**</KeypointsItem>
</Keypoints>
```

result:

## What you'll learn

- First item
- Second **item**
]]></page>
<page path="/authoring/img" title="`Img`"><![CDATA[URL: /authoring/img
Description: Using images in documentation

# `Img`

Using images in documentation

Display images using markdown, HTML or `<Img>` syntax with automatic dimensions and relative path support.

## Relative paths

Relative images are supported. Eg, inside your [`MDX`](introduction#configuration:~:text=MDX) folder:

```text {2}
|-- authoring
|   |-- img.mdx  <= relative to this article
|   `-- gutenberg.jpg
```

```md title="authoring/img.mdx"
---
title: Authoring
---

![](gutenberg.jpg)
```

result:

![](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

> \[!TIP] You are encouraged to use relative images, since dimensions are automatically added as `img[width][height]` attributes.
>
> For others, think about adding them to **prevent layout shift**.

## Dimensions

It is also possible to specify only one dimension (other is inferred from intrinsic ratio), eg:

```md
<img src="gutenberg.jpg" height="200" />
```

result:

![](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

`<Img>` written as such works like `<img>`: relative `src` resolved, dimensions read:

```md
<Img src="gutenberg.jpg" height="200" />
```

result:

![](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

## Sizing with CSS

Although it is probably better to use CSS for this:

```md
<img src="gutenberg.jpg" style={{width: 'auto', height: '10rem'}} />
```

result:

![](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

> \[!NOTE] See [`MDX_BASEURL`](/getting-started/introduction#configuration:~:text=MDX_BASEURL) to understand how it is converted to a full URL, or to a root-relative one.
]]></page>
<page path="/authoring/code" title="`Code`"><![CDATA[URL: /authoring/code
Description: Code blocks with syntax highlighting, line numbers, file names and collapsing

# `Code`

Code blocks with syntax highlighting, line numbers, file names and collapsing

Code blocks with syntax highlighting.

## File name

A `title="..."` shows a file name above the code, with the icon of its file type:

````md
```ts title="lib/utils.ts"
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
```
````

result:

```ts title="lib/utils.ts"
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
```

The icon follows the file extension, or else the language of the block: TypeScript, React (`.tsx`, `.jsx`), JavaScript, CSS, JSON, YAML, HTML, Markdown, MDX, a terminal for shell scripts, a generic code file otherwise.

## Collapsible

A long block can show only its first lines, until the reader expands it, with `collapsible` (with or without a `title`):

````md
```css title="src/styles/globals.css" collapsible
@import 'tailwindcss';

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --radius-lg: var(--radius);
}

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}
```
````

result:

```css title="src/styles/globals.css" collapsible
@import 'tailwindcss';

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --radius-lg: var(--radius);
}

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}
```

The copy button copies the whole block, collapsed or not. A `collapsible` block short enough to show whole stays as it is.

## From a file

A `file="..."` fills the block with a file, relative to the page, so the page shows the file as it is rather than a copy of it that drifts. Whatever the fence holds is replaced, so leave it empty:

````md
```tsx title="Example.tsx" file="Example.tsx" collapsible
```
````

result:

```tsx title="Example.tsx" collapsible
'use client'

import { useState } from 'react'

type ExampleProps = {
  /** Starting value supplied by the MDX scope. */
  initialCount: number
}

/**
 * A documentation example registered through the repository's docs.config.ts.
 */
export function Example({ initialCount }: ExampleProps) {
  const [count, setCount] = useState(initialCount)

  return (
    <button
      type="button"
      className="rounded border px-3 py-2"
      data-testid="custom-component-example"
      data-count={count}
      onClick={() => setCount(count + 1)}
    >
      Count: {count}
    </button>
  )
}
```

A file that cannot be read fails the build. The path may lead out of the MDX folder, e.g. `file="../../dev.sh"` for a script at the root of the repository, but must stay inside the repository holding the page: a path out of it fails the build.

## Line numbers and highlights

Line numbers/highlights are supported:

````md
```tsx {1,4-6} showLineNumbers
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```
````

result:

```tsx {1,4-6} showLineNumbers
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```

## Starting line number

You can start at a specific `X` line number `showLineNumbers=X`:

````md
```tsx {1,4-6} showLineNumbers=150
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```
````

result:

```tsx {1,4-6} showLineNumbers=150
type Props = {who: string}

function Hi({who}: Props) {
  return (
    <p>Hello, {who}!</p>
  )
}
```

## Diff

`diff` format is supported:

````md
```diff
diff --git a/example.txt b/example.txt
index 8c3317a..47ea956 100644
--- a/example.txt
+++ b/example.txt
@@ -1,4 +1,4 @@
-Hello, World!
+Hello, GitHub World!
 Here are some changes:
-This line will be modified.
+This line has been modified.
 This line will stay the same.
```
````

result:

```diff
diff --git a/example.txt b/example.txt
index 8c3317a..47ea956 100644
--- a/example.txt
+++ b/example.txt
@@ -1,4 +1,4 @@
-Hello, World!
+Hello, GitHub World!
 Here are some changes:
-This line will be modified.
+This line has been modified.
 This line will stay the same.
```

## Package managers

npm commands in a `bash`, `sh` or `shell` block get a tab per package manager:

````md
```bash
npm install three
```
````

result:

```bash
npm install three
```
]]></page>
<page path="/authoring/mermaid" title="Mermaid"><![CDATA[URL: /authoring/mermaid
Description: Creating diagrams with Mermaid

# Mermaid

Creating diagrams with Mermaid

[Mermaid](https://mermaid.js.org/) text-based diagrams. Automatically adapt to light/dark theme.

````md
```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]
```
````

result:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]
```

---

````md
```mermaid
sequenceDiagram
    participant User
    participant Browser
    User->>Browser: Click button
    Browser-->>User: Display result
```
````

result:

```mermaid
sequenceDiagram
    participant User
    participant Browser
    User->>Browser: Click button
    Browser-->>User: Display result
```

---

[KaTeX support](https://github.com/mermaid-js/mermaid/pull/2885):

````md
```mermaid
graph LR
    A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$")
    A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$")
    B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
    C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
```
````

result:

```mermaid
graph LR
    A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$")
    A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$")
    B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
    C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
```
]]></page>
<page path="/authoring/grid" title="`Grid` (Deprecated)"><![CDATA[URL: /authoring/grid
Description: Responsive grid layout component

# `Grid` (Deprecated)

Responsive grid layout component

> \[!CAUTION]
>
> Deprecated, use [tailwind `grid-cols-*`](https://tailwindcss.com/docs/grid-template-columns) instead.

Responsive grid layout.

```md
<Grid cols={2}>
  <li>A</li>
  <li>B</li>
  <li>C</li>
  <li>D</li>
  <li>E</li>
  <li>F</li>
  <li>G</li>
</Grid>
```

result:

- A

- B

- C

- D

- E

- F

- G
]]></page>
<page path="/authoring/sandpack" title="`Sandpack`"><![CDATA[URL: /authoring/sandpack
Description: Inline sandboxes for interactive code examples

# `Sandpack`

Inline sandboxes for interactive code examples

Interactive code sandboxes powered by CodeSandbox.

> \[!NOTE] See Sandpack [official documentation](https://sandpack.codesandbox.io/docs/getting-started/usage) for full usage.

> \[!WARNING] `three` resolving to `0.186.0` or higher (`latest` included) is pinned to `0.185.1` automatically: since `0.186.0`, its CommonJS entry calls `process.emitWarning`, which Sandpack's in-browser bundler does not provide (the preview fails with `process.emitWarning is not a function`).

```tsx
<Sandpack
  template="react-ts"
  customSetup={{
    dependencies: {
      'three': 'latest',
      '@react-three/fiber': 'latest',
      '@react-three/drei': 'latest'
    },
  }}
  files={{
    '/styles.css': `html,body,#root {height:100%;margin:unset;}`,
    '/App.tsx': `import { Canvas } from '@react-three/fiber'
import { Cloud, CameraControls } from '@react-three/drei'

export default function App() {
  return (
    <Canvas camera={{position: [0,-13,0]}}>
      <Cloud speed={.4} growth={6} />
      <ambientLight intensity={Math.PI} />
      <CameraControls />
    </Canvas>
  )
}`,
  }}
/>
```

result:

Interactive code example (available on the documentation website).

> \[!TIP] Sandpack UI SSR-rendering[^1] is also supported (out of the box).

#### `Sandpack[folder]`

Instead of `files`, a `folder` prop allows you to pass a folder containing all the files:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
/>
```

`folder` path is relative to the `.mdx` file:

```text
|-- getting-started
|   |-- authoring.mdx             <= relative to this article
|   `-- authoring-sandpack-cloud     <= the folder
```

> \[!TIP] It will simply:
>
> - build the `files` prop for you (including all `.{js|ts|jsx|tsx|css}` it finds)
> - build `customSetup.dependencies` from `package.json` if it exists

result:

Interactive code example (available on the documentation website).

---

It is also possible to pass some individual [file format](https://sandpack.codesandbox.io/docs/getting-started/usage#file-format) configuration:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  files={{
    '/App.tsx': {
      readOnly: true,
      active: true,
    },
    '/styles.css': {
      hidden: true
    }
  }}
/>
```

result:

Interactive code example (available on the documentation website).

#### `Sandpack[fileExplorer]`

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  fileExplorer
/>
```

result:

Interactive code example (available on the documentation website).

> \[!TIP] Conveniently, enabling `fileExplorer` will by default `[codeEditor={showTabs: false}]`. You can override it with [`[codeEditor]` options](#sandpack%5Bcodeeditor%5D)

---

You can also pass [any `fileExplorer={options: ComponentProps<SandpackFileExplorer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#file-explorer:~:text=Preview-,Options,-If%20you%27re%20looking).

#### `Sandpack[codeEditor]`

You can pass [any `codeEditor={options: ComponentProps<SandpackCodeEditor>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor:~:text=Preview-,Options,-Extensions).

#### `Sandpack[codeViewer]`

It will render the [`SandpackCodeViewer`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer) instead of the default [`SandpackCodeEditor`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor).

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer
/>
```

result:

Interactive code example (available on the documentation website).

You can also pass [any `codeViewer={options: ComponentProps<SandpackCodeViewer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer:~:text=Preview-,Options,-CodeMirror%20decorations).

##### `Sandpack[codeViewer][filesDecorators]`

You can define per-file [decorators](https://sandpack.codesandbox.io/docs/advanced-usage/components#codemirror-decorations) through `filesDecorators` prop:

```tsx
<Sandpack
  template="react-ts"
  folder="authoring-sandpack-cloud"
  codeViewer={{
    filesDecorators: {
      '/App.tsx': [
        { className: "highlight", line: 1 },
        { className: "highlight", line: 7 },
        {
          className: "widget",
          elementAttributes: { "data-id": "1" },
          line: 7,
          startColumn: 13,
          endColumn: 24,
        },
        {
          className: "widget",
          elementAttributes: { "data-id": "2" },
          line: 7,
          startColumn: 25,
          endColumn: 35,
        },
        
      ],
      '/styles.css': [
        { className: "highlight", line: 4 },
      ]
    }
  }}
/>
```

result:

Interactive code example (available on the documentation website).

#### `Sandpack[preview]`

You can pass [any `preview={options: ComponentProps<SandpackPreview>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#preview:~:text=Preview-,Options,-Additional%20buttons).

[^1]: <https://sandpack.codesandbox.io/docs/guides/ssr#nextjs-app-dir>
]]></page>
<page path="/authoring/codesandbox" title="`Codesandbox`"><![CDATA[URL: /authoring/codesandbox
Description: Embed Codesandbox examples

# `Codesandbox`

Embed Codesandbox examples

Embed live CodeSandbox examples.

Linked previews use shadcn `Card` with optional title, description and `Badge` tags. The preview image or placeholder remains the link to CodeSandbox. Interactive embeds keep their iframe.

Give the sandbox a preview image with `img`. Like an [`<img src>`](img), it can be relative to the article:

```text {2}
|-- authoring
|   |-- codesandbox.mdx  <= relative to this article
|   `-- cell-fracture.webp
```

```md
<Codesandbox id="3rjsl" title="Cell fracture" img="cell-fracture.webp" />
```

result:

[Cell fracture](https://codesandbox.io/s/3rjsl)

> \[!TIP] A relative `img` gets its dimensions added automatically, just as a relative [`Img`](img) does. A full URL (`img="https://…"`) works too, as is.

The same image is the page's thumb in the [`Entries`](entries) listing.

## Without `img`

CodeSandbox no longer serves screenshots of sandboxes, so without `img` a placeholder stands in, still linking to the sandbox:

```md
<Codesandbox id="3rjsl" title="Cell fracture" />
```

result:

[Cell fracture](https://codesandbox.io/s/3rjsl)

Optional metadata can accompany either an image or a placeholder:

```md
<Codesandbox
  id="3rjsl"
  title="Cell fracture"
  description="Explore a physics example with Rapier."
  tags={["physics", "rapier"]}
/>
```

[Cell fracture](https://codesandbox.io/s/3rjsl)

Explore a physics example with Rapier.

With only an `id`, the placeholder link is still labelled `CodeSandbox` followed by that id.

> \[!NOTE] `screenshot_url` is the former name of `img`. It still works, but is deprecated.

## Props

| Prop          | Type       | Description                                                     |
| ------------- | ---------- | --------------------------------------------------------------- |
| `id`          | `string`   | Sandbox id, e.g. `3rjsl` for `https://codesandbox.io/s/3rjsl`   |
| `title`       | `string`   | Caption under the preview                                       |
| `img`         | `string`   | Preview image: relative to the article, or a full URL           |
| `description` | `string`   | Text under the title                                            |
| `tags`        | `string[]` | Tags under the title, e.g. `tags={["physics", "rapier"]}`       |
| `embed`       | `boolean`  | Embeds the live sandbox in an `iframe` instead of linking to it |
]]></page>
<page path="/authoring/gha" title="`Gha`"><![CDATA[URL: /authoring/gha
Description: GitHub-style alerts and callouts

# `Gha`

GitHub-style alerts and callouts

GitHub-style alerts with multiple severity levels.

Aka. ["GitHub alerts"](https://github.com/orgs/community/discussions/16925)

Callouts compose shadcn `Card` parts with each kind's Material background and matching foreground. The icon-and-label header sits above full-width rich content, using the standard Card spacing. They remain static editorial notes, so reading an article does not trigger an assertive screen-reader announcement.

```md
<Gha keyword="NOTE">Highlights information that users should take into account, even when skimming.</Gha>
```

or better:

```md
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
```

result:

> \[!NOTE] Highlights information that users should take into account, even when skimming.

---

We also support: `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`

result:

> \[!TIP] Optional information to help a user be more successful.

> \[!IMPORTANT] Crucial information necessary for users to succeed.

> \[!WARNING] Critical content demanding immediate user attention due to potential risks.

> \[!CAUTION] Negative potential consequences of an action.

---

The `title` prop overrides the label derived from `keyword` (icon and background still follow the keyword). Only available via the JSX form:

```md
<Gha keyword="TIP" title="MCP-server">Browse these docs from your MCP-compatible client.</Gha>
```

result:

> \[!TIP] **MCP-server**
>
> Browse these docs from your MCP-compatible client.

Rich Markdown also works inside a callout:

> \[!NOTE] Keep **headings, links and lists** in your existing authoring content:
>
> - Read the [Keypoints](keypoints) before starting.
> - Open the [sandbox examples](codesandbox) to try the ideas.

Custom labels wrap in full, and rich blocks retain their structure:

> \[!TIP] **Before sharing a sandbox, check its dependencies and document the environment needed to reproduce the example**
>
> ### Reproduce the example
>
> Run the example locally before sharing it:
>
> ```sh
> pnpm install
> pnpm dev
> ```
>
> - Document the requirements.
>   - Include the supported Node.js version.
> - Link to the [sandbox examples](codesandbox).
]]></page>
<page path="/authoring/badge" title="`Badge`"><![CDATA[URL: /authoring/badge
Description: Small tags, like "storybook" or "suspense"

# `Badge`

Small tags, like "storybook" or "suspense"

Small tags, usually right under the page title.

## Usage

```md
<Badge href="https://drei.pmnd.rs/?path=/story/abstractions-positionalaudio--positional-audio-scene-st">storybook</Badge>
<Badge href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>
<Badge>Dom only</Badge>
```

result:

[storybook](https://drei.pmnd.rs/?path=/story/abstractions-positionalaudio--positional-audio-scene-st) [suspense](https://r3f.docs.pmnd.rs/api/hooks#useloader) Dom only

A badge is inline, like a link: badges on consecutive lines make one row, and a badge sits in a sentence too, as in "works with suspense".

## Color

`color` takes a color role of the theme: `primary`, `secondary`, `tertiary`, `error`, or one of the custom colors `note`, `tip`, `important`, `warning`, `caution`; or a brand color, `storybook`, `npm`, `chromatic`, shown as is, with white text, in light and dark alike (see `THEME_*` in [configuration](/getting-started/introduction#configuration)):

```md
<Badge color="primary">primary</Badge>
<Badge color="secondary">secondary</Badge>
<Badge color="tertiary">tertiary</Badge>
<Badge color="error">error</Badge>
<Badge color="note">note</Badge>
<Badge color="tip">tip</Badge>
<Badge color="important">important</Badge>
<Badge color="warning">warning</Badge>
<Badge color="caution">caution</Badge>
<Badge color="storybook" logo="storybook">storybook</Badge>
<Badge color="npm" logo="npm">npm</Badge>
<Badge color="chromatic" logo="chromatic">chromatic</Badge>
<Badge color="tip" href="https://r3f.docs.pmnd.rs/api/hooks#useloader">suspense</Badge>
```

result:

primary secondary tertiary error note tip important warning caution storybook npm chromatic [suspense](https://r3f.docs.pmnd.rs/api/hooks#useloader)

## Label and logo

`label` adds a de-emphasized label before the text, and `logo` a brand logo, by its [simple-icons](https://simpleicons.org) slug — for now `storybook`, `chromatic`, `discord`, `github` or `npm`; any other shows none:

```md
<Badge href="https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei" label="GitHub" logo="github">Open in Codespaces</Badge>
```

result:

[GitHub Open in Codespaces](https://github.com/codespaces/new?template_repository=pmndrs%2Fdrei)

## shields.io images

A [shields.io](https://shields.io) image is an image like any other: it is not turned into a `Badge`. For a badge that follows the theme, write `<Badge>`.
]]></page>
<page path="/authoring/hint" title="`Hint` (Deprecated)"><![CDATA[URL: /authoring/hint
Description: Deprecated hint component

# `Hint` (Deprecated)

Deprecated hint component

> \[!CAUTION] Deprecated, use [`Gha[keyword="NOTE"]`](gha) instead.

Existing `Hint` markup still renders the same static note through the shadcn Card composition.

```md
<Hint>
  I'm a deprecated hint. Use `Gha` instead.
</Hint>
```

result:

> \[!NOTE]
>
> I'm a deprecated hint. Use `Gha` instead.
]]></page>
<page path="/authoring/contributors" title="`Contributors`"><![CDATA[URL: /authoring/contributors
Description: Display repository contributors

# `Contributors`

Display repository contributors

Display GitHub repository contributors.

```md
<Contributors owner="pmndrs" repo="docs" />
```

> \[!WARNING] [`CONTRIBUTORS_PAT`](introduction#configuration:~:text=CONTRIBUTORS_PAT) needs to be set. Otherwise, it will display John Doe.

result:

[Contributors](https://github.com/pmndrs/docs/graphs/contributors)
]]></page>
<page path="/authoring/backers" title="`Backers`"><![CDATA[URL: /authoring/backers
Description: Display project backers

# `Backers`

Display project backers

Display Open Collective backers.

```md
<Backers repo="react-three-fiber" />
```

result:

[Backers](https://opencollective.com/react-three-fiber#backers)
]]></page>
<page path="/authoring/entries" title="`Entries`"><![CDATA[URL: /authoring/entries
Description: Display a grouped directory listing of documentation pages

# `Entries`

Display a grouped directory listing of documentation pages

Displays all documentation entries in a multi-column layout, grouped by category.

The `Entries` component automatically generates a directory listing of all documentation pages in the site, organized by their top-level category (first segment of the slug).

```md
<Entries />
```

result:

- [pmndrs/docs](/getting-started/introduction)
- [Authoring](/authoring/introduction)
- [\`Intro\`](/authoring/intro)
- [\`Keypoints\`](/authoring/keypoints)
- [\`Img\`](/authoring/img)
- [\`Code\`](/authoring/code)
- [Mermaid](/authoring/mermaid)
- [\`Grid\` (Deprecated)](/authoring/grid)
- [\`Sandpack\`](/authoring/sandpack)
- [\`Codesandbox\`](/authoring/codesandbox)
- [\`Gha\`](/authoring/gha)
- [\`Badge\`](/authoring/badge)
- [\`Hint\` (Deprecated)](/authoring/hint)
- [\`Contributors\`](/authoring/contributors)
- [\`Backers\`](/authoring/backers)
- [\`Entries\`](/authoring/entries)
- [Reusable GitHub Actions workflow](/github-actions/introduction)
- [Agents](/agents/introduction)
- [\`Steps\`](/authoring/steps)
- [\`Tabs\`](/authoring/tabs)
- [\`Carousel\`](/authoring/carousel)
- [\`Color\`](/authoring/color)
- [\`ScrollArea\`](/authoring/scroll-area)
- [\`scroll-fade\`](/authoring/scroll-fade)
- [\`full-bleed\`](/authoring/full-bleed)
- [Custom components and data](/authoring/custom-components)

> \[!TIP] When a page includes a [`<Codesandbox>`](codesandbox) component, the Entries listing will automatically display its [`img`](codesandbox) as a thumb next to that page's link, or a CodeSandbox icon when it has none.
]]></page>
<page path="/github-actions/introduction" title="Reusable GitHub Actions workflow"><![CDATA[URL: /github-actions/introduction
Description: Call from your CI

# Reusable GitHub Actions workflow

Call from your CI

This project provides a [`build.yml` reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#calling-a-reusable-workflow) you can easily call from your own project workflow.

In your `.github/workflows` folder, create a eg. `docs.yml` file:

```yml title=".github/workflows/docs.yml"
uses: pmndrs/docs/.github/workflows/build.yml@v4
  with:
    mdx: 'docs'
    libname: 'React Three Fiber'
    libname_short: 'r3f'
    home_redirect: '/getting-started/introduction'
    icon: '🇨🇭'
    logo: '/logo.png'
    github: 'https://github.com/pmndrs/react-three-fiber'
    discord: 'https://discord.com/channels/740090768164651008/740093168770613279'
```

With no `theme_*` input, the site gets the pmndrs palette. Each input is a `THEME_*` variable of the [configuration](/getting-started/introduction#configuration).

See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation.

## Custom components and data

The CLI discovers `docs.config.ts` at the checked-out repository root. See [Custom components and data](/authoring/custom-components) for its `components` and `scope` fields.

The reusable workflow does not install your repository's dependencies or expose a custom configuration path. If your components import packages or your configuration lives elsewhere, use your own build job: check out the repository, set up Node, install its dependencies, then run the CLI:

```sh
npx @pmndrs/docs build docs out --format website --libname 'My library' --config config/docs.config.ts
```

Set the website's [configuration](/getting-started/introduction#configuration) in that job and deploy the generated `out` folder. `--config` is optional when using the root `docs.config.ts`.

## Version switcher

Optional inputs for the [version switcher](/getting-started/introduction#version-switcher); `version_production_branch` defaults to the repository's default branch.

| input                       | env                         |
| --------------------------- | --------------------------- |
| `lib_version`               | `LIB_VERSION`               |
| `tag_match`                 | `TAG_MATCH`                 |
| `version_url_template`      | `VERSION_URL_TEMPLATE`      |
| `version_production_branch` | `VERSION_PRODUCTION_BRANCH` |
| `version_production_url`    | `VERSION_PRODUCTION_URL`    |
| `version_branches`          | `VERSION_BRANCHES`          |
| `version_branches_list`     | `VERSION_BRANCHES_LIST`     |

eg. for a monorepo package whose branches are deployed by Vercel's Git integration:

```yml title=".github/workflows/docs.yml"
uses: pmndrs/docs/.github/workflows/build.yml@v4
  with:
    # ...
    tag_match: 'leva@*'
    version_url_template: 'https://leva-git-{branch:vercel}-pmndrs.vercel.app'
```

With `version_url_template`, the workflow outputs where the switcher links the branch being built: `version_url`, and its hostname, `version_hostname` -- a long branch already cut and hashed to fit the hostname label. A deployment the Git integration does not make needs that alias set, eg. for a `vercel deploy` in a later job:

```yml title=".github/workflows/docs.yml"
jobs:
  build:
    uses: pmndrs/docs/.github/workflows/build.yml@v4
    with:
      # ...
      version_url_template: 'https://mylib-git-{branch}-myteam.vercel.app'

  vercel:
    needs: build
    steps:
      # ... `vercel deploy`, its URL in `steps.vercel-deploy.outputs.url`
      - run: npx -y vercel alias set "$DEPLOYMENT" "$ALIAS" --token="$VERCEL_TOKEN" --scope=myteam
        env:
          DEPLOYMENT: ${{ steps.vercel-deploy.outputs.url }}
          ALIAS: ${{ needs.build.outputs.version_hostname }}
```
]]></page>
<page path="/agents/introduction" title="Agents"><![CDATA[URL: /agents/introduction
Description: llms.txt dumps, and the pmndrs MCP server

# Agents

llms.txt dumps, and the pmndrs MCP server

Every site built with this generator publishes machine-readable dumps of its content, and [docs.pmnd.rs](https://docs.pmnd.rs) serves them to agents over MCP.

## llms.txt

Each site publishes [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt), linked in the HTML head:

```html
<link rel="alternate" type="text/plain" href="/llms.txt" />
<link rel="alternate" type="text/plain" href="/llms-full.txt" />
```

## MCP server

[MCP server requests, live](https://docs.pmnd.rs/mcp/live)

`llms-full.txt` is too big to paste into an agent. The [MCP](https://modelcontextprotocol.io) server lets an agent read an index first, then fetch only the page it needs.

One endpoint for all libraries, over streamable HTTP: `https://docs.pmnd.rs/api/mcp`.

| kind     | name                     | gives                                                           |
| -------- | ------------------------ | --------------------------------------------------------------- |
| resource | `docs://pmndrs/manifest` | the libraries served, and how to query them                     |
| resource | `docs://{lib}/index`     | a library's pages, one `{path} - {title}` per line              |
| tool     | `get_page_content`       | one page as markdown, given a `lib` and a `path`                |
| resource | `examples://index`       | the [examples](https://pmndrs.github.io/examples), one per line |
| tool     | `get_example`            | one example in full, given a `name` from that index             |

eg. _"how do I use TypeScript with Zustand?"_:

```txt
read  docs://zustand/index
      → [...] /learn/guides/beginner-typescript - Beginner TypeScript Guide [...]

call  get_page_content(lib="zustand", path="/learn/guides/beginner-typescript")
      → the page, as markdown
```

### Install

With Claude Code, use [`pmndrs/claude-code-plugin`](https://github.com/pmndrs/claude-code-plugin):

```sh
/plugin marketplace add pmndrs/claude-code-plugin
/plugin install pmndrs@pmndrs
```

For other clients, copy the JSON config from the MCP box on the [home page](https://docs.pmnd.rs). The server is also listed on the [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pmndrs/docs) as `io.github.pmndrs/docs`.

### Inspect

```sh
$ HOST=127.0.0.1 npx -y @modelcontextprotocol/inspector
```

Then **Add Servers** › **Add manually**, transport `streamable-http`, URL `https://docs.pmnd.rs/api/mcp` (or `http://localhost:3000/api/mcp`), and toggle the server on.

![MCP Inspector connected to docs.pmnd.rs, previewing the react-three-fiber index resource](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/agents/mcp-inspector.png)

## Examples

The same endpoint serves the [examples gallery](https://pmndrs.github.io/examples), for questions about how something is put together rather than what an API takes:

```txt
read  examples://index
      → [...] caustics · #transmission [...]
        diamond-refraction · Diamon refraction material · +postprocessing,leva · #refraction,bvh

call  get_example(name="caustics")
      → its source, live URL, asset attribution and dependency versions
```

In an index line, `+` lists dependencies beyond `@react-three/fiber` and `@react-three/drei`, and a trailing `~23k` flags a large example by its token cost.

An example pins its own versions: for a current API signature, check the docs.

`pmndrs/examples` publishes these documents at build time, each linked from its page as `<link rel="alternate" type="text/markdown">`:

| URL                     | content                                       |
| ----------------------- | --------------------------------------------- |
| `/examples/caustics`    | the page                                      |
| `/examples/caustics.md` | the example, as `get_example` returns it      |
| `/llms.txt`             | the gallery, as `examples://index` returns it |

## Serving your library

Libraries publishing `/llms-full.txt` are served, and badged `MCP` on [docs.pmnd.rs](https://docs.pmnd.rs). To join:

1. **Publish the dump.** Build with this generator, `v3.4.1` or later, eg. with the [reusable workflow](/github-actions/introduction). Otherwise, emit the same `<page path="…" title="…">…</page>` shape yourself.
2. **Check it.** `curl -sI <NEXT_PUBLIC_URL>/llms-full.txt` must return `200`, and the body must contain `<page …>` entries.
3. **Flip the flag.** Open a PR on [pmndrs/docs](https://github.com/pmndrs/docs) setting `llms_full: true` on your entry in `libs` ([`src/app/page.tsx`](https://github.com/pmndrs/docs/blob/main/src/app/page.tsx)). It takes effect on the next push to `main`.

Once served, content updates need no redeploy: pages are fetched at request time and revalidated every 5 minutes.
]]></page>
<page path="/authoring/steps" title="`Steps`"><![CDATA[URL: /authoring/steps
Description: Numbered steps, one per `Step` heading

# `Steps`

Numbered steps, one per `Step` heading

Numbers a sequence of steps, like an installation guide.

Every `Step` inside `Steps` is the heading of a new step, numbered automatically; whatever follows it (paragraphs, code blocks…) is the content of that step. Unlike a `###`, a `Step` has no anchor, and no entry in the table of contents.

````md
<Steps>

  <Step>Install the dependencies</Step>

  ```sh
  npm install three @react-three/fiber
  ```

  <Step>Create a scene</Step>

  Render a `Canvas`, with a mesh in it:

  ```tsx
  import { Canvas } from '@react-three/fiber'

  export default function App() {
    return (
      <Canvas>
        <mesh>
          <boxGeometry />
          <meshNormalMaterial />
        </mesh>
      </Canvas>
    )
  }
  ```

  <Step>Run it</Step>

  That's it: start your dev server.

</Steps>
````

result:

### Install the dependencies

```sh
npm install three @react-three/fiber
```

### Create a scene

Render a `Canvas`, with a mesh in it:

```tsx
import { Canvas } from '@react-three/fiber'

export default function App() {
  return (
    <Canvas>
      <mesh>
        <boxGeometry />
        <meshNormalMaterial />
      </mesh>
    </Canvas>
  )
}
```

### Run it

That's it: start your dev server.
]]></page>
<page path="/authoring/tabs" title="`Tabs`"><![CDATA[URL: /authoring/tabs
Description: Alternative contents, one shown at a time

# `Tabs`

Alternative contents, one shown at a time

Alternative contents, one shown at a time.

## Usage

```md
<Tabs defaultValue="react">
  <TabsList>
    <TabsTrigger value="react">React</TabsTrigger>
    <TabsTrigger value="vue">Vue</TabsTrigger>
    <TabsTrigger value="svelte">Svelte</TabsTrigger>
  </TabsList>
  <TabsContent value="react">

    | Aspect | React |
    | --- | --- |
    | Type | Library |
    | Templates | JSX |
    | Reactivity | Re-render on state change |

  </TabsContent>
  <TabsContent value="vue">

    | Aspect | Vue |
    | --- | --- |
    | Type | Framework |
    | Templates | Single-file components with HTML templates |
    | Reactivity | Reactive proxies |

  </TabsContent>
  <TabsContent value="svelte">

    | Aspect | Svelte |
    | --- | --- |
    | Type | Compiler |
    | Templates | `.svelte` files |
    | Reactivity | Compiled at build time |

  </TabsContent>
</Tabs>
```

result:

**React**

**Vue**

**Svelte**

| Aspect     | React                     |
| ---------- | ------------------------- |
| Type       | Library                   |
| Templates  | JSX                       |
| Reactivity | Re-render on state change |

| Aspect     | Vue                                        |
| ---------- | ------------------------------------------ |
| Type       | Framework                                  |
| Templates  | Single-file components with HTML templates |
| Reactivity | Reactive proxies                           |

| Aspect     | Svelte                 |
| ---------- | ---------------------- |
| Type       | Compiler               |
| Templates  | `.svelte` files        |
| Reactivity | Compiled at build time |

Same API as [shadcn `Tabs`](https://ui.shadcn.com/docs/components/base/tabs).

`defaultValue` is required (otherwise no tab is shown until hydration).

Markdown inside a `TabsContent` (a table, a code block, a list) needs a blank line after the opening tag and before the closing one.

## Rich triggers

Triggers accept any markup:

```md
<Tabs defaultValue="react">
  <TabsList>
    <TabsTrigger value="react">React <Badge>19</Badge></TabsTrigger>
    <TabsTrigger value="vue">Vue</TabsTrigger>
  </TabsList>
  <TabsContent value="react">

    | Aspect | React |
    | --- | --- |
    | Version | 19 |
    | Released | December 2024 |

  </TabsContent>
  <TabsContent value="vue">

    | Aspect | Vue |
    | --- | --- |
    | Version | 3 |
    | Released | September 2020 |

  </TabsContent>
</Tabs>
```

result:

**React 19**

**Vue**

| Aspect   | React         |
| -------- | ------------- |
| Version  | 19            |
| Released | December 2024 |

| Aspect   | Vue            |
| -------- | -------------- |
| Version  | 3              |
| Released | September 2020 |

## Synced tabs

Tabs of the same `syncKey` switch together: picking a tab in one picks it in every other, on this page and on the others. The pick is remembered (in `localStorage`), after a reload and in other browser tabs.

```md
<Tabs defaultValue="react" syncKey="framework">
  <TabsList>
    <TabsTrigger value="react">React</TabsTrigger>
    <TabsTrigger value="vue">Vue</TabsTrigger>
    <TabsTrigger value="svelte">Svelte</TabsTrigger>
  </TabsList>
  <TabsContent value="react">

    Templates are JSX: markup in JavaScript.

  </TabsContent>
  <TabsContent value="vue">

    Templates are HTML, in single-file components.

  </TabsContent>
  <TabsContent value="svelte">

    Templates are HTML, in `.svelte` files.

  </TabsContent>
</Tabs>

<Tabs defaultValue="react" syncKey="framework">
  <TabsList>
    <TabsTrigger value="react">React</TabsTrigger>
    <TabsTrigger value="svelte">Svelte</TabsTrigger>
  </TabsList>
  <TabsContent value="react">

    State changes re-render the component.

  </TabsContent>
  <TabsContent value="svelte">

    State changes are compiled into DOM updates.

  </TabsContent>
</Tabs>
```

result:

**React**

**Vue**

**Svelte**

Templates are JSX: markup in JavaScript.

Templates are HTML, in single-file components.

Templates are HTML, in `.svelte` files.

**React**

**Svelte**

State changes re-render the component.

State changes are compiled into DOM updates.

A `Tabs` without the picked tab stays as it is: pick Svelte above, then Vue, and the second one stays on Svelte. The pick is still Vue, for the next `Tabs` that has it. A page loaded with a pick none of its tabs have shows their `defaultValue`.

The page's HTML shows `defaultValue`: the picked tab replaces it once the page's JavaScript runs. A link to a `#hash` in a hidden panel opens its tab as a click would, so it picks that tab too.
]]></page>
<page path="/authoring/carousel" title="`Carousel`"><![CDATA[URL: /authoring/carousel
Description: Slides shown one or a few at a time, scrolled by dragging or with arrows

# `Carousel`

Slides shown one or a few at a time, scrolled by dragging or with arrows

Slides shown one (or a few) at a time: drag them, or click an arrow, then use the left and right arrow keys.

Same API as [shadcn `Carousel`](https://ui.shadcn.com/docs/components/base/carousel), built on [Embla](https://www.embla-carousel.com/) (`opts` takes [Embla's options](https://www.embla-carousel.com/api/options/)).

## Usage

```jsx
<Carousel>
  <CarouselContent>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">1</div>
    </CarouselItem>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">2</div>
    </CarouselItem>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">3</div>
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

result:

1

2

3

The arrows sit inside the article's width, in a gutter: on each side, or above and below a vertical carousel.

## Two at a time

```jsx
<Carousel opts={{ align: "start" }}>
  <CarouselContent>
    <CarouselItem className="basis-1/2">
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">1</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">2</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">3</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">4</div>
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

result:

1

2

3

4

## Vertical

The strip needs a height:

```jsx
<Carousel orientation="vertical">
  <CarouselContent className="h-80">
    <CarouselItem className="basis-1/2">
      <div className="flex h-full items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">1</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex h-full items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">2</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex h-full items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">3</div>
    </CarouselItem>
    <CarouselItem className="basis-1/2">
      <div className="flex h-full items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">4</div>
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

result:

1

2

3

4

## Without arrows

Drag only, and `loop` so there is always a next slide. No arrows, no gutter.

```jsx
<Carousel opts={{ loop: true }}>
  <CarouselContent>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">1</div>
    </CarouselItem>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">2</div>
    </CarouselItem>
    <CarouselItem>
      <div className="flex aspect-video items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">3</div>
    </CarouselItem>
  </CarouselContent>
</Carousel>
```

result:

1

2

3

## Images

```jsx
<Carousel opts={{ loop: true }}>
  <CarouselContent>
    <CarouselItem>
      <Img src="gutenberg.jpg" alt="Gutenberg" />
    </CarouselItem>
    <CarouselItem>
      <Img src="gutenberg.jpg" alt="Gutenberg" />
    </CarouselItem>
    <CarouselItem>
      <Img src="gutenberg.jpg" alt="Gutenberg" />
    </CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

result:

![Gutenberg](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

![Gutenberg](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

![Gutenberg](https://github.com/pmndrs/docs/raw/dependabot/github_actions/pnpm/action-setup-6/docs/authoring/gutenberg.jpg)

In the markdown export of a page, the slides follow one another, without the arrows.
]]></page>
<page path="/authoring/color" title="`Color`"><![CDATA[URL: /authoring/color
Description: Swatches of the theme's color roles

# `Color`

Swatches of the theme's color roles

[storybook](https://main--6977e41687a50b30c4349650.chromatic.com/?path=/docs/color--docs)

Shows a color role of the theme as a swatch, as Material's scheme poster does.

## Usage

A `Color` is a swatch of a role, the role in kebab-case: a disc of its color, the role as its tooltip.

```md
<Color role="primary" />
```

result:

`primary`

The role is any Material role of the theme, `primary`, `surface-container-high`, `on-tertiary-fixed-variant`… or one of its custom colors (see `THEME_*` in [configuration](/getting-started/introduction#configuration)) -- the seven pmndrs ones, `lime`, `teal`, `cyan`, `purple`, `red`, `orange` and `yellow`, the alert ones, and the site's own too, from `THEME_CUSTOM_COLORS`: `brand:#ff2d95` there makes `<Color role="brand" />` here, following the scheme, contrast and primary like any role. A color is inline, like a badge: colors on consecutive lines make one row, and a color sits in a sentence too.

```md
<Color role="lime" />
<Color role="teal" />
<Color role="cyan" />
<Color role="purple" />
<Color role="red" />
<Color role="orange" />
<Color role="yellow" />
<Color role="note" />
<Color role="tip" />
<Color role="important" />
<Color role="warning" />
<Color role="caution" />
```

result:

`lime` `teal` `cyan` `purple` `red` `orange` `yellow` `note` `tip` `important` `warning` `caution`

`size` sets the diameter, `sm`, `md` (the default) or `lg`.

## Cells

`variant="cell"` makes it a cell, a rounded square of `size` with the role's name on it in the color Material pairs it with, as on Material's scheme poster. The label is the role in Title Case; `children` replaces it. `ink` picks another text role.

```md
<Color role="inverse-primary" variant="cell" />
```

result:

`inverse-primary`

## Groups

A `ColorGroup` fuses cells into one rounded block, `horizontal` (side by side, the default) or `vertical` (stacked), each cell filling its column. In a group, a cell says so, `variant="cell"`, or `variant="on"` for the strip of the role that goes on it:

```md
<ColorGroup orientation="vertical">
  <Color role="primary" variant="cell" />
  <Color role="on-primary" variant="on" />
</ColorGroup>
```

result:

`primary` `on-primary`

Groups nest, a horizontal one as a row of a vertical one:

```md
<ColorGroup orientation="vertical">
  <ColorGroup>
    <Color role="secondary-fixed" variant="cell" size="lg" />
    <Color role="secondary-fixed-dim" variant="cell" size="lg" />
  </ColorGroup>
  <Color role="on-secondary-fixed" variant="on" />
  <Color role="on-secondary-fixed-variant" variant="on" />
</ColorGroup>
```

result:

`secondary-fixed` `secondary-fixed-dim`

`on-secondary-fixed` `on-secondary-fixed-variant`

## Any color

`color` takes any CSS color as is, for one that is not a role of the theme, e.g. a brand color; `ink` is then any CSS color too, white by default:

```md
<Color color="var(--brand-storybook)" />
<Color color="#cb3837" variant="cell">npm</Color>
```

result:

`var(--brand-storybook)` `#cb3837`npm

## Poster

The two compose into material-theme-builder's [scheme poster](https://main--695eb517cb602e59b4cc045c.chromatic.com/?path=/story/mtb--custom-colors-color-match-st), of the theme of this site, in the scheme of the toggle: its grid, three accents wide and the error column, a group in each cell.

```md
<div className="grid! grid-cols-[3fr_1fr] gap-2">
  <ColorGroup>
    {['primary', 'secondary', 'tertiary'].map((role) => (
      <ColorGroup key={role} orientation="vertical">
        <Color role={role} variant="cell" />
        <Color role={`on-${role}`} variant="on" />
        <Color role={`${role}-container`} variant="cell" />
        <Color role={`on-${role}-container`} variant="on" />
      </ColorGroup>
    ))}
  </ColorGroup>
  <ColorGroup orientation="vertical">
    <Color role="error" variant="cell" />
    <Color role="on-error" variant="on" />
    <Color role="error-container" variant="cell" />
    <Color role="on-error-container" variant="on" />
  </ColorGroup>
  <ColorGroup>
    {['primary', 'secondary', 'tertiary'].map((role) => (
      <ColorGroup key={role} orientation="vertical">
        <ColorGroup>
          <Color role={`${role}-fixed`} variant="cell" />
          <Color role={`${role}-fixed-dim`} variant="cell" />
        </ColorGroup>
        <Color role={`on-${role}-fixed`} variant="on" />
        <Color role={`on-${role}-fixed-variant`} variant="on" />
      </ColorGroup>
    ))}
  </ColorGroup>
  <div />
  <ColorGroup orientation="vertical">
    <ColorGroup>
      <Color role="surface-dim" variant="cell" />
      <Color role="surface" variant="cell" />
      <Color role="surface-bright" variant="cell" />
    </ColorGroup>
    <ColorGroup>
      <Color role="surface-container-lowest" variant="cell" />
      <Color role="surface-container-low" variant="cell" />
      <Color role="surface-container" variant="cell" />
      <Color role="surface-container-high" variant="cell" />
      <Color role="surface-container-highest" variant="cell" />
    </ColorGroup>
    <ColorGroup>
      <Color role="on-surface" variant="on" />
      <Color role="on-surface-variant" variant="on" />
      <Color role="outline" variant="on" />
      <Color role="outline-variant" variant="on" />
    </ColorGroup>
  </ColorGroup>
  <ColorGroup orientation="vertical">
    <Color role="inverse-surface" variant="cell" />
    <Color role="inverse-on-surface" variant="on" />
    <Color role="inverse-primary" variant="on" />
    <ColorGroup>
      <Color role="scrim" variant="on" />
      <Color role="shadow" variant="on" />
    </ColorGroup>
  </ColorGroup>
  <ColorGroup orientation="vertical" className="col-span-2">
    {['note', 'tip', 'important', 'warning', 'caution'].map((color) => (
      <ColorGroup key={color}>
        <Color role={color} variant="cell" />
        <Color role={`on-${color}`} variant="cell" />
        <Color role={`${color}-container`} variant="cell" />
        <Color role={`on-${color}-container`} variant="cell" />
      </ColorGroup>
    ))}
  </ColorGroup>
</div>
```

result:

`primary` `on-primary` `primary-container` `on-primary-container`

`secondary` `on-secondary` `secondary-container` `on-secondary-container`

`tertiary` `on-tertiary` `tertiary-container` `on-tertiary-container`

`error` `on-error` `error-container` `on-error-container`

`primary-fixed` `primary-fixed-dim`

`on-primary-fixed` `on-primary-fixed-variant`

`secondary-fixed` `secondary-fixed-dim`

`on-secondary-fixed` `on-secondary-fixed-variant`

`tertiary-fixed` `tertiary-fixed-dim`

`on-tertiary-fixed` `on-tertiary-fixed-variant`

`surface-dim` `surface` `surface-bright`

`surface-container-lowest` `surface-container-low` `surface-container` `surface-container-high` `surface-container-highest`

`on-surface` `on-surface-variant` `outline` `outline-variant`

`inverse-surface` `inverse-on-surface` `inverse-primary`

`scrim` `shadow`

`note` `on-note` `note-container` `on-note-container`

`tip` `on-tip` `tip-container` `on-tip-container`

`important` `on-important` `important-container` `on-important-container`

`warning` `on-warning` `warning-container` `on-warning-container`

`caution` `on-caution` `caution-container` `on-caution-container`
]]></page>
<page path="/authoring/scroll-area" title="`ScrollArea`"><![CDATA[URL: /authoring/scroll-area
Description: A box that scrolls its content, with a custom scrollbar

# `ScrollArea`

A box that scrolls its content, with a custom scrollbar

A box of a given size that scrolls its content, with a custom scrollbar.

Same API as [shadcn `ScrollArea`](https://ui.shadcn.com/docs/components/base/scroll-area), built on [Base UI](https://base-ui.com/react/components/scroll-area).

## Usage

It needs a size to scroll within, e.g. `h-72`:

```md
<ScrollArea className="h-72 rounded-2xl border">
  <div className="p-4">

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam.

  </div>
</ScrollArea>
```

result:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam.

Markdown inside needs a blank line before and after it, as in any JSX tag.

## Horizontal

Add a `<ScrollBar orientation="horizontal" />`, and keep the content on one line (`w-max`):

```jsx
<ScrollArea className="rounded-2xl border">
  <div className="flex w-max gap-4 p-4">
    <div className="flex h-40 w-56 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">1</div>
    <div className="flex h-40 w-56 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">2</div>
    <div className="flex h-40 w-56 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">3</div>
    <div className="flex h-40 w-56 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">4</div>
    <div className="flex h-40 w-56 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">5</div>
  </div>
  <ScrollBar orientation="horizontal" />
</ScrollArea>
```

result:

1

2

3

4

5

In the markdown export of a page, the content is written out in full, without the box.
]]></page>
<page path="/authoring/scroll-fade" title="`scroll-fade`"><![CDATA[URL: /authoring/scroll-fade
Description: A fade on the edges of a scroll container, that follows the scroll position

# `scroll-fade`

A fade on the edges of a scroll container, that follows the scroll position

A fade on the edges of a scroll container, where there is more content to scroll to.

[shadcn's `scroll-fade`](https://ui.shadcn.com/docs/utils/scroll-fade) utility classes, available in any `className`: see its page for every class (`scroll-fade-t`, `scroll-fade-<number>`, `scroll-fade-none`…).

## Usage

On the element that scrolls, the one with `overflow-y-auto`:

```jsx
<div className="overflow-hidden rounded-2xl border">
  <div className="h-72 scroll-fade overflow-y-auto">
    <div className="flex flex-col gap-1.5 p-1.5">
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 1</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 2</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 3</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 4</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 5</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 6</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 7</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 8</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 9</div>
      <div className="rounded-lg bg-surface-container px-3 py-2.5">Item 10</div>
    </div>
  </div>
</div>
```

result:

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

At the top, only the bottom edge fades; mid-scroll, both; at the end, only the top. Content that does not overflow does not fade. In browsers without `animation-timeline: scroll()`, both edges fade, always.

The fade is a mask: it dissolves the content, and the border of the element with it. For a crisp border, put it on a wrapper.

## Horizontal

`scroll-fade-x`, on the element with `overflow-x-auto`:

```jsx
<div className="scroll-fade-x overflow-x-auto">
  <div className="flex w-max gap-1.5">
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Design</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Engineering</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Marketing</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Product</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Research</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Sales</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Support</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Operations</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Finance</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Legal</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">People</div>
    <div className="rounded-lg bg-surface-container px-3 py-2.5">Security</div>
  </div>
</div>
```

result:

Design

Engineering

Marketing

Product

Research

Sales

Support

Operations

Finance

Legal

People

Security
]]></page>
<page path="/authoring/full-bleed" title="`full-bleed`"><![CDATA[URL: /authoring/full-bleed
Description: A block as wide as the article, past the reading column

# `full-bleed`

A block as wide as the article, past the reading column

A block as wide as the article, past the reading column.

Every block of a page is no wider than the reading column. With `full-bleed` in its `className`, a block takes the whole width of the article instead, from the `xl` breakpoint, without the side margin other blocks keep: it reaches the article's edges. The difference only shows on a screen wide enough for the article to be wider than the column.

## Usage

On a block at the top level of the page, not nested in another one:

```jsx
<div className="full-bleed flex h-40 items-center justify-center rounded-2xl bg-surface-container text-3xl font-bold">full-bleed</div>
```

result:

full-bleed

compared to a block without it:

default
]]></page>
<page path="/authoring/custom-components" title="Custom components and data"><![CDATA[URL: /authoring/custom-components
Description: Use your React components and shared data in MDX

# Custom components and data

Use your React components and shared data in MDX

Make your React components and data available to every MDX page.

Create a component and some data:

```tsx title="docs/authoring/Example.tsx"
'use client'

import { useState } from 'react'

export function Example({ initialCount }: { initialCount: number }) {
  const [count, setCount] = useState(initialCount)
  return (
    <button className="rounded border px-3 py-2" onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  )
}
```

```json title="docs/authoring/Example.json"
{
  "initialCount": 3,
  "spacing": [
    { "name": "compact", "value": 4 },
    { "name": "comfortable", "value": 12 }
  ]
}
```

Register them in `docs.config.ts` at your repository root:

```ts title="docs.config.ts"
import type { DocsConfig } from '@pmndrs/docs/src/config'
import { Example } from './docs/authoring/Example'
import example from './docs/authoring/Example.json'

export default {
  components: { Example },
  scope: { example },
} satisfies DocsConfig
```

Then use them directly in MDX:

```md
<Example initialCount={example.initialCount} />
```

result:

Count: 3

Click the counter to increment it.

Server components

Components can also load data asynchronously on the server, without `'use client'`:

```tsx title="docs/authoring/Example.server.tsx"
export async function ExampleTable() {
  const { default: example } = await import('./Example.json')
  return (
    <table>
      <thead>
        <tr>
          <th>Spacing</th>
          <th>Pixels</th>
        </tr>
      </thead>
      <tbody>
        {example.spacing.map(({ name, value }) => (
          <tr key={name}>
            <th scope="row">{name}</th>
            <td>{value}</td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}
```

Import `ExampleTable` into `docs.config.ts` and add it to `components`, then use it in MDX:

```md
<ExampleTable />
```

result:

| Spacing     | Pixels |
| ----------- | ------ |
| compact     | 4      |
| comfortable | 12     |

## Rendering

Registered components override built-in components with the same name. Keep the configuration on the server. Add `'use client'` to interactive component modules and pass serializable props.

Website builds support CSS imports. For Tailwind classes in external components, include their files in your own Tailwind stylesheet's sources and import that stylesheet from the configuration.

HTML fragments render only the initial state, without hydration or stylesheets: the counter above displays its starting value but does not respond to clicks.

See [Configuration](/getting-started/introduction#configuration) for config paths and CLI options, and [GitHub Actions](/github-actions/introduction#custom-components-and-data) for CI setup.
]]></page>