PreviewFrame
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.
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
<Callout Variant="tip" Title="A live example">Switch to the Code tab above to see the source for this box.</Callout>| Prop | 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.
| Prop | 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:
```razor:preview stretch
<TypeTable>
<TypeRow Name="Title" Type="string?" Description="Optional title." />
</TypeTable>
```
| Prop | Type | Default | Description |
|---|---|---|---|
Title |
string? |
— | Optional title. |
<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.
| Prop | 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.
<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
| Prop | 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. |