Skip to Content
rehype-code-group

Sync and persistence

Make related groups switch together, and remember the reader's choice in local storage or the URL.

A reader who picks pnpm in one install block usually wants pnpm in every block on the page, and on the next page too. Two attributes on rich groups handle this:

  • sync joins groups under a shared key.
  • persist saves the selection for that key.

Sync

Groups with the same sync key switch together. The client matches tabs by value, not by position or label.

:::: code-group label="Package manager" sync="pm-demo"

::: code-tab label="npm" value="npm"

```sh
npm install rehype-code-group
```

:::

::: code-tab label="pnpm" value="pnpm"

```sh
pnpm add rehype-code-group
```

:::

::::

Try it: choose a tab in either group below.

npm install rehype-code-group
pnpm add rehype-code-group
yarn add rehype-code-group
npm run build
pnpm run build
yarn run build

How it behaves:

  • A group that has no tab with the chosen value keeps its current tab.
  • Groups added to the page later, for example after client-side navigation, start on the value last chosen for their key.
  • Only the group you clicked fires the rehype-code-group:change event. The groups that follow it don't.
  • Compact groups have no attributes, so they can't sync. Convert a group to the rich syntax to give it a sync key.

Persist

persist decides where the choice for a sync key is stored. It does nothing without sync, because the key names the stored value.

ValueStored inGood for
locallocalStorage, under rehype-code-group:<sync key>Remembering a reader's preference across pages and visits.
urlThe query string, as ?rcg-<sync key>=<value>Links that open with a particular tab selected.

With persist="url", the client updates the address with history.replaceState. That changes the current history entry without adding a new one, so the back button isn't affected.

If storage is unavailable, for example in some private browsing modes or sandboxed frames, the client keeps working and doesn't save the choice.

Which tab is selected on load

When the client sets up a group, it picks the first of these that matches one of the group's tab values:

  1. The persisted value: the URL parameter for persist="url", or local storage for persist="local".
  2. The value already chosen for the same sync key earlier in this page session.
  3. The default attribute, which is already in the generated HTML.
  4. The first tab.

When a persisted value is found, other enhanced groups with the same key switch to it too.

This page's demos use sync="pm-demo" without persist, so reloading the page resets them.

Edit on GitHub