# PreviewFrame

> The frame around every live example. Preview and Code tabs, a copy button, an actions menu, and three layouts.

Source: https://shelldocs.shellui.dev/docs/components/preview-frame

`PreviewFrame` is the frame around every live example on a ShellDocs site. A `razor:preview` fence, a `DemoPreview` and a `ComponentPreview` all render through it, so they share one toolbar and one set of layouts.

> **You rarely write PreviewFrame yourself**
>
> Author examples as `razor:preview` fences and the framework wraps them. Reach for `PreviewFrame` directly only when you build a custom page outside `DocsPage`.

## The toolbar

```razor
<Callout Variant="tip" Title="A live example">Switch to the Code tab above to see the source for this box.</Callout>
```

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `Preview \| Code` | `tabs` |  | Preview shows the live component. Code shows the highlighted source. Arrow keys, Home and End move between them. |
| `Copy` | `button` |  | Copies the source exactly as written. A check mark confirms the copy. |
| `Open in new tab` | `menu` |  | Opens the page at this example's anchor. |
| `Report a bug` | `menu` |  | Opens a new issue pre-filled with the example name and page URL. |
| `Suggest something` | `menu` |  | Same, labelled as a suggestion. |

The two issue links point at `ShellDocsOptions.IssueTrackerUrl`, which defaults to the new-issue page of `GitHubRepo`. With neither set they are hidden.

The toolbar is driven by `shelldocs.js`, so it works on static hosts. A tab picked before the Blazor circuit starts is kept when the circuit takes over.

## Layouts

A frame centres its example by default. Two other layouts cover examples that don't suit that.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `center` | `default` |  | Centres the example and shrinks it to its content. Right for buttons, badges, small cards. |
| `stretch` | `opt-in` |  | Block-level components fill the frame's width. Right for tables, inputs, charts, tabs. |
| `scroll` | `opt-in` |  | An example wider than the frame scrolls inside it on small screens. Right for toolbars and pagination. A scroll box clips popovers, so only use it when needed. |

On a fence, add the layout after the language:

````markdown
```razor:preview stretch
<TypeTable>
<TypeRow Name="Title" Type="string?" Description="Optional title." />
</TypeTable>
```
````

```razor
<TypeTable>
<TypeRow Name="Title" Type="string?" Description="Optional title." />
</TypeTable>
```

On `DemoPreview` and `ComponentPreview`, set `Layout="stretch"` or `Layout="scroll"`.

On phones the frame's side padding shrinks, and an example that is still too wide starts at the left edge instead of being cut off on both sides.

## Anchors

Every frame has a stable id, used by *Open in new tab* and safe to link to.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `preview-1, preview-2, …` | `fence` |  | razor:preview fences, numbered in page order. |
| `demo-{component}` | `DemoPreview` |  | From the component name. Override with the Id parameter when a page shows the same demo twice. |
| `example-{component}-{hash}` | `ComponentPreview` |  | The hash comes from the source, so two previews of one component get different ids. |

## Page typography stays out

A frame carries the `not-prose` class. Page styles for paragraphs, lists, headings and links skip it, so a component inside a frame looks the way it does in a real app. Add `not-prose` to any element of your own that should be left alone.

## Errors

When a fence names a component that isn't registered, the frame shows a red panel naming the tag and pointing at the registration call, instead of falling back to a plain code block.

```razor
<NotARegisteredComponent Title="Oops" />
```

Attributes that can't be applied are skipped with a logged warning and the component still renders. That covers event callbacks, `@bind-*`, `@ref`, values that can't be converted to the parameter's type, and unknown attributes on a component with no catch-all.

## Props

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `Preview` | `PreviewSlot?` | `—` | A parsed razor:preview fence. Built by the markdown pipeline. |
| `Content` | `RenderFragment?` | `—` | Content mode: what to render in the Preview tab. |
| `Code` | `string?` | `—` | Content mode: the source shown in the Code tab. |
| `Language` | `string` | `razor` | Highlighting language for the Code tab. |
| `Title` | `string?` | `—` | Optional title in the frame header. |
| `Layout` | `string?` | `center` | center, stretch or scroll. |
| `Id` | `string?` | `—` | Anchor id. Must be the same on every render of the page. |
| `Name` | `string?` | `component name` | Used in issue titles. |
| `Error` | `string?` | `—` | Shows the error panel with this message instead of the example. |
| `ErrorTitle` | `string` | `razor:preview error` | Heading of the error panel. |

## See also

- [razor:preview](https://shelldocs.shellui.dev/docs/authoring/razor-preview.md): How to write the fence.
- [DemoPreview](https://shelldocs.shellui.dev/docs/components/demo-preview.md): Examples that need a code block of their own.
- [ComponentPreview](https://shelldocs.shellui.dev/docs/components/component-preview.md): A preview written as a tag.
- [Configuration](https://shelldocs.shellui.dev/docs/getting-started/configuration.md): IssueTrackerUrl and the other options.