Preview

Docgo provides two complementary preview paths:

• ::: playground renders the MDX already on the page and can pair it with a Code tab.
• <ClientPreview /> lazily loads a registered React component and mounts it with createRoot in the browser.

Use a playground for static examples. Use ClientPreview for Storybook-like stories that need state, effects, event handlers, or browser APIs.

#Canvas layout

Both preview types support the same canvas layouts:

centered is the default. minHeight sets the initial/minimum canvas height in pixels, and autoHeight controls whether an iframe follows its content height.

:::: playground [Dashboard]{layout="fullscreen" minHeight="360" autoHeight="false"}

<Dashboard />

```tsx [preview source]
<Dashboard />
```

::::

A playground can contain a preview only, code only, or both. Docgo only shows tabs for the modes that exist.

#Isolation

The default isolation="iframe" keeps Docgo prose CSS out of the example. Choose isolation="inline" when the example intentionally needs the parent document's layout or inherited CSS variables.

:::: playground [Theme sample]{isolation="inline" layout="padded"}

<ThemeSwatch />

```tsx [preview source]
<ThemeSwatch />
```

::::

Iframe isolation is CSS and DOM isolation, not a security sandbox. Preview modules are trusted application code, and browser globals referenced by a module still belong to the documentation page. When code must target the iframe document, derive it from a rendered node's ownerDocument.

#Interactive ClientPreview

Put preview modules under docs/previews. Files ending in .preview.ts, .preview.tsx, .preview.js, or .preview.jsx are discovered automatically.

import { useState } from 'react';

export default function Counter({ initial = 0 }: { initial?: number }) {
  const [count, setCount] = useState(initial);
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

The preview name is the relative path without the .preview.* suffix. The module above is named forms/counter.

<ClientPreview
  name="forms/counter"
  props={{ initial: 3 }}
  layout="centered"
  minHeight={240}
/>

props must be JSON serializable. The complete canvas API is:

#Combine preview and source

Wrap ClientPreview in a playground to get Preview/Code tabs. Docgo automatically keeps the outer playground inline so the client island can mount; the ClientPreview still controls its own isolation and canvas.

:::: playground [Counter]

<ClientPreview name="forms/counter" layout="padded" minHeight={240} />

```tsx [preview source]
<Counter initial={3} />
```

::::

#Preview stylesheets

Preview iframes copy user stylesheets from the page head, while excluding Docgo-managed stylesheets by default. Add product CSS through head or headFile. To opt a Docgo-managed stylesheet into every preview iframe, list its href in previewStylesheets.

export default defineConfig({
  previewStylesheets: ['assets/bmates-ui.css'],
});

The current light/dark theme is synchronized to preview iframe documents.

#Preview provider

Use previewProvider as a global Storybook-style decorator for every ClientPreview, including inline previews. It receives children, name, and props.

import type { ReactNode } from 'react';
import { StyleProvider } from 'your-design-system';
import 'your-design-system/styles.css';

export default function PreviewProvider({ children }: { children?: ReactNode }) {
  return <StyleProvider>{children}</StyleProvider>;
}

import { defineConfig } from '@kyechan99/docgo';

export default defineConfig({
  previewProvider: { module: './docs/previews/provider.tsx' },
});

Set export when the provider is a named export.

#Explicit registration

Use clientPreviews for modules outside docs/previews or for named exports. An explicit entry overrides an auto-discovered preview with the same name.

export default defineConfig({
  clientPreviews: {
    chart: {
      module: './src/previews/chart.tsx',
      export: 'ChartPreview',
    },
  },
});

During development, edits and additions/removals under docs/previews, as well as changes to clientPreviews and previewProvider, are picked up without restarting Docgo.