Preview
The preview lets you see a component on every target at once while you work on it. Think of a button you restyle in React and only later find too narrow in Svelte, a prop you rename that Angular no longer reads, or an agent asked for a screenshot of a card in seven frameworks that opens seven apps to take it.
unframework preview starts one dev server per target your unframework.config.ts names, and a page that shows the selection in one labelled frame per target. Pick an example or a component in the sidebar, and change its props in the controls panel, a component's own or those of the components an example renders: every target renders the same thing with the same props.
This page walks you through it. We'll look at:
- Running it with
unframework preview. - What it shows: your examples and your components.
- The page: the sidebar, the canvas, the controls panel and the keyboard.
- Example metadata: the category, title, description and order of each example.
- Controls: the props the preview can set, on a component and in an example.
- How it works: the servers, the frames and what it writes.
- Building a static preview with
unframework preview build. - Embedding an example in another page, by its own URL.
- Deploying it to any static host.
Run it
unframework preview comes with @uxfront/unframework, and needs @unframework.dev/visual and vite in your project, beside what unframework visual needs. The sample design system runs it from a script of its package.json:
"preview": "unframework preview",
It prints the page's URL, then each target's server, and runs until you press Ctrl+C, which stops every server. These are its options:
| Option | What it does |
|---|---|
--target <t> | Shows one target, and can be repeated. By default it shows every target of your configuration. |
--port <n> | The page's port. By default the system picks a free one, and each target's server always does. |
It exits 0 once you stop it, and 2 on a usage or configuration error, a project with no example and no component, or a package it needs that isn't installed.
The preview is for your machine while you develop: every server listens on 127.0.0.1 only. Each target's compiler stack, like Angular's, comes from package.resolveFrom, as for unframework test.
What it shows
The sidebar lists your examples first, then your components. An example is a *.example.uf.tsx file with no props, found as unframework visual finds it. A component is the default export of a .uf.tsx file under srcDir, an example excepted. A file with no default export, or one that doesn't compile, isn't listed, and unframework check says why.
The page opens on the first example, and keeps the selection in its URL, so a reload or a link shows the same thing. Each frame's caption names its target and says whether it rendered, or why it failed.
A component renders with props alone, so its slots are empty and its models keep their defaults. To see a component with content, write an example that fills it, as examples/Buttons.example.uf.tsx does for Button.
The page
The page has three parts, side by side:
- The sidebar holds your examples as a tree of their categories, and your components below it, by their paths. The filter at the top keeps the items whose name, or whose group's name, holds what you type.
- The canvas shows the selection's title and description, and one frame per target. Targets above the frames shows them all side by side, or one at a time at the canvas's full size. A preview of one target shows it at the canvas's full size from the start, with no Targets switch.
- The controls panel holds the controls of the selected component, or of each component the selected example renders, and names the props it can't set.
In a narrow window, the three stack: the sidebar, then the canvas, then the controls.
The page follows your system's light or dark setting. The moon button at the top of the sidebar switches between the two, and the page keeps your choice for the next time you open it. The frames keep a white page in both, since your components bring their own colours.
Everything works from the keyboard. Press ? to list these shortcuts on the page:
| Key | What it does |
|---|---|
/ | Moves to the filter. |
Esc | Clears the filter. |
↓ in the filter | Moves to the first item of the tree. |
↑ and ↓ | Move through the tree. |
← and → | Close or open a group, or move out of or into it. |
Home and End | Move to the tree's first or last item. |
Enter | Shows the item, or opens or closes a group. |
? | Lists the shortcuts. |
/ and ? do nothing while you type in a field.
Example metadata
The page lists your examples under their categories, by their titles. A doc comment on an example's default export sets them:
/**
* Every colour the theme defines, on the solid variant.
* @category Components/Actions/Button
* @title Colors
* @order 2
*/
export default function ButtonColors() { … }
The comment has to sit directly on export default. Its text is the example's description. These are the tags it reads, and it ignores any other:
| Tag | What it sets | Without it |
|---|---|---|
@category | The groups the example sits in, outermost first, separated by /. | The example's directory, or its parent's when the directory is examples. |
@title | The example's name in the list. | The file name in words, without the category's own words in front. |
@order | Where it sits among the others, as a number: lower comes first. | After every example that has one. |
@layout | How it sits in its frame, as Example layout says. | Centred in its frame. |
So without a comment, src/components/button/examples/ButtonColors.example.uf.tsx is Colors in Button, and src/components/field-group/examples/FieldGroupDefault.example.uf.tsx is Default in Field Group: the directory's name in title case, with - and _ as spaces. An example at your project's root, or in a root examples/, is in Examples.
Examples sort by @order, then by title, then by id. An empty @category or @title, an @order that isn't a number, a malformed @layout, or a tag given twice is a warning, UF7012, which the preview prints when it starts, and preview build when it builds. It then uses the value it derives instead.
The comment changes nothing that renders, so unframework visual doesn't read it, and an example keeps its id and its baselines.
Example layout
Each frame centres its example by default, so a small component like a button sits in the middle of its frame rather than in a corner. @layout changes how it sits, the way display: flex would on the element the example mounts in:
/**
* The two sizes, stacked.
* @layout column align-start gap
*/
export default function ButtonSizes() { … }
Its value is words in any order, at most one of each kind. A kind you leave out keeps its default:
| Words | What they set | Without them |
|---|---|---|
row, column | The direction, flex-direction. | row |
justify-start, justify-center, justify-end, justify-between, justify-around, justify-evenly | The alignment along the direction, justify-content. | justify-center |
align-start, align-center, align-end, align-stretch, align-baseline | The alignment across it, align-items. | align-center |
wrap | Whether the items wrap, flex-wrap. | No wrapping |
gap-xs, gap-sm, gap, gap-lg, gap-xl | The gap, from a scale. | 0 |
gap-<length> | The gap, as 0 or a length in px, rem or em. | 0 |
The scale is 0.25rem, 0.5rem, 1rem, 1.5rem and 2rem, so a bare gap matches the frame's padding. Reach for a length only when the scale doesn't fit: gap-8px, gap-0.5rem and gap-0 work, while gap-8 and gap-.5rem don't. A layout takes one gap, from the scale or a length.
A flex layout keeps 1rem of padding around the example and fills the frame's height. Centre and end alignment are safe, so an example larger than its frame starts at its top-left edge and you can scroll to the rest.
@layout none turns all of this off: the example fills the frame's width, as a plain block with no padding. It's the one to pick for a page section or a form that should take the whole width.
The layout sits on the frame's container alone, so the example's own elements look exactly as the component renders them. A component you select in the list is centred, like an example without the tag. An empty value, a word the list doesn't have, two words of one kind or none with other words is UF7012, and the preview centres that example.
Controls
A component gets one control for each prop whose type the preview can set:
| Prop type | Control |
|---|---|
boolean | A checkbox |
string | A text field |
number | A number field |
| A union of string literals | A list of its values |
The type can be an alias, even one imported from another file. The sample design system's Button takes a variant?: ButtonVariant, from its src/types.ts:
export type ButtonVariant = "primary" | "secondary";
So its variant gets a list of primary and secondary. Change it, and every frame renders the button again with the new value, in place.
An optional prop starts unset, so the component's own default applies, and its control offers "(default)" to go back to it. A blank text or number field leaves an optional prop unset too. A required prop starts at false, an empty string, 0 or the first value of its union.
A prop of any other type, like a function, an object or a union of numbers, gets no control. The page names it, with its type.
Controls on an example
An example gets the controls of the components it renders, so you can see ButtonColors disabled, or in another size, without writing another example. The panel shows one group per component, in the order the example first renders each, headed by the component's name, and by its path too when two groups share a name.
A control's value reaches every instance of that component in the example that doesn't set the prop itself, whatever its value, an instance inside another component's slot included. A prop an instance sets keeps that instance's value. Take the sample design system's examples/Buttons.example.uf.tsx:
import Button from "../src/Button.uf.tsx";
export default function Buttons() {
return (
<div>
<Button>Save</Button> <Button variant="secondary">Cancel</Button>
</div>
);
}
Set its variant control to secondary, and Save turns secondary, while Cancel keeps the secondary it sets. Set it to primary, and Cancel still keeps secondary.
A prop that every instance sets gets no control, since no instance would take its value: the group names it under "Set by the example". A required prop is always there, because every instance must set it. Every control on an example starts at "(default)", which means "as the example wrote it", so a boolean gets a list of "(default)", true and false rather than a checkbox. A reload, or another selection, starts every control at "(default)" again, as on a component.
Only the components under srcDir that the preview lists get controls. A component the example file declares itself, the instances inside it, a component from a package and an instance that <component is> renders are left as written. So is an example that declares props, which is UF7011, or one that doesn't compile: the panel says it has no controls, and the frames show its errors.
The preview reads which controls an example gets when it starts. An instance you add while it runs gets the controls its component already has, and a component new to the example gets its controls once you restart.
How it works
Each target gets a Vite dev server of its own, built the way unframework test builds a browser project: the plugins of your config's vite, like a styling engine's, then the Unframework plugin for that target, then the target's own plugins, in that order within each of Vite's enforce groups. Each listens on a port of its own, so each frame has an origin of its own, and the frameworks never share a page. The page sends each frame the selection and its props with postMessage, and each frame mounts it with that target's mount adapter, the one the tests use. Astro has no client runtime, so its frame asks its own server to render on the server, and inserts the HTML.
An example's controls are props the preview gives the example itself. Each target's server rewrites an example before it compiles it: the example takes one optional prop per control, and each instance that doesn't set the control's prop gets it bound, as in <Button variant={ufPreview.ufControl0}>. "(default)" leaves the prop unset, so the component's own default applies.
The rewrite keeps every line where it was, so an error points at the right line. It's the preview's alone: your files don't change, and unframework visual and unframework test render the example as written.
Each server calls vite with its target and mode: "preview", for plugins of its own, and merges the other keys it returns into its config, as a test project does. It refuses the same keys, server.host, server.port and server.hmr among them, so the preview never listens beyond your machine.
The preview writes nothing beside your sources. Vite keeps each server's cache in node_modules/.vite, and Angular's compiler keeps its scratch in .uf-tmp/, in the directory its stack resolves from.
The first time a target meets a dependency it hasn't bundled yet, Vite bundles it and reloads that frame. The frame then asks for the selection again, so you don't have to do anything.
From a script, startPreview({ root, targets?, port?, toolchainDirs? }) from @unframework.dev/visual starts the same servers. It resolves to { url, frames, diagnostics, close } once every one listens: url is the page's, frames lists each target's origin and port, diagnostics holds the UF7012 warnings of your examples' doc comments, and close() stops them all. That's how an agent takes a screenshot of the page with Playwright, then stops the preview.
Build a static preview
unframework preview build writes the same preview as a static site, so you can publish it for the people who use your components, or give each pull request a link to it. It builds each target's frame with Vite, on the configuration its dev server uses, and writes the page that frames them beside them:
unframework preview build --out dist/preview
It prints any UF7012 warning of your examples, then where it wrote the site and the targets it built, and exits 0. These are its options:
| Option | What it does |
|---|---|
--target <t> | Builds one target, and can be repeated. By default it builds every target of your configuration. |
--out <dir> | The site's directory, relative to your project. By default it's .unframework/preview, which examples are never under. |
The build empties --out first, so it refuses your project's directory, a directory above it, and one that isn't empty and that no earlier build wrote. Those refusals exit 2, like a usage or configuration error, a project with nothing to show, or a build that fails.
The site is the page as index.html, and one directory per target, like react/ and vue/, with that target's frame as frame.html. Every URL in it is relative, so a static host serves it at any path, with no rewrites and no server. Open it at its directory's URL with the final slash, like https://example.com/preview/: without it, the page's relative URLs resolve from the directory above.
It runs what the dev preview runs, with three differences:
- Every frame shares the page's origin, so the frames share storage and cookies. An example that reads
localStoragecan see what another target's frame wrote there. A frame that the page drives answers only a page of its own origin, so another site can't frame it and drive it. An embedded example takes one message at most, its colour mode, from the page that frames it. - Astro shows each entry with its first props only. The site has no server to render Astro, so the build renders each example and each component once, with the props the page first sends it, which for an example is every control at "(default)", and the Astro frame shows that render. Change a control, on a component or an example, and the Astro frame says it can't render it, while every other target renders it. Go back to the first values, and it renders again. An embed with controls on Astro does the same: it shows the message in place of the example, and the panel stays.
- The frames are development builds, as the dev servers serve, so they're bigger than a production build. A path under your project, or its repository, appears relative to it, so the site carries no path of the machine that built it.
From a script, buildPreview({ root, targets?, out?, toolchainDirs? }) from @unframework.dev/visual writes the same site, and resolves to { out, targets, diagnostics }, where diagnostics holds those warnings.
Embed an example
Each example has a URL of its own on each target, which shows that example alone, with no sidebar or canvas. Put it in an <iframe>, and a docs page, a blog post or a design-system site shows the example live, in the framework you pick. The URL sits beside the page:
embed.html?example=<id>&target=<target>
example is the example's id, its path without .example.uf.tsx, like examples/Card. target is one of the names in the frames' captions, like vue or solid2. Both are required. So a site at https://example.com/preview/ shows the sample design system's card in Vue with:
<iframe src="https://example.com/preview/embed.html?example=examples/Card&target=vue" title="Card, in Vue"></iframe>
We recommend giving each <iframe> a title, since that's the name a screen reader gives the frame. The Open link in each frame's caption opens the selected example's URL on that target in a new tab, so you can copy it from there.
embed.html checks the example and the target, then replaces itself with that target's frame, which renders the example once. An unknown or missing example or target shows a message in the frame instead, so an embed is never a blank page. The URL is the contract: the frame's own URL, where embed.html sends the browser, may change.
Three optional parameters ask for more:
| Parameter | Values | What it does |
|---|---|---|
controls | true | Shows the example's controls below it. |
theme | light, dark | Sets the colour mode, which the page that frames it can then change. |
resize | true | Sends the example's height to the page that frames it. |
embed.html checks each value, and any other one, like theme=blue, shows a message that names the values it takes. With none of the three, the embed shows the example alone and takes and sends no messages.
Show the controls
With controls=true, the embed shows the example's controls below it, as the page's Controls panel shows them, and each change renders the example again. A prop the example sets itself keeps its value, as in the page. The panel keeps its own styles, so your project's global styles, on body, label or select, reach the example and not the panel.
When you set the <iframe>'s height, the example takes the space above the panel, and the panel takes at most half the frame. Each scrolls on its own when its content is taller. With resize=true too, nothing scrolls: the embed reports the height of both.
Set the colour mode
theme=light or theme=dark sets data-theme on the embed's <html>, with the matching color-scheme, before the example renders. Styleframe's themes select [data-theme="dark"], so a Styleframe project's dark theme applies. The panel follows the mode too. Without theme, the embed follows the reader's system.
With theme in its URL, the embed also takes the mode from the page that frames it, so the page can change it without a reload, and the control values stay. The page posts this message to the <iframe>:
iframe.contentWindow.postMessage({ type: "unframework:embed", kind: "theme", theme: "dark" }, "https://example.com");
Name the preview's origin as the target, as above, so the message reaches only your preview. The embed takes it only from its parent window, only with exactly these three keys and only with light or dark. It ignores every other message.
Size the iframe to its content
With resize=true, the embed sends its height, in whole CSS pixels, to the page that frames it, once it has rendered and whenever the height changes:
{ type: "unframework:embed", kind: "resize", height: 148 }
The page sets the <iframe>'s height from it. Check that the message comes from that <iframe>, since any frame on the page can post one:
<iframe id="card" src="https://example.com/preview/embed.html?example=examples/Card&target=vue&controls=true&theme=light&resize=true" title="Card, in Vue"></iframe>
<script>
const card = document.getElementById("card");
addEventListener("message", (event) => {
if (event.source !== card.contentWindow) return;
if (event.data?.type !== "unframework:embed" || event.data.kind !== "resize") return;
card.style.height = `${event.data.height}px`;
});
// Call this from the site's colour mode switch.
function setEmbedTheme(theme) {
const message = { type: "unframework:embed", kind: "theme", theme };
card.contentWindow.postMessage(message, "https://example.com");
}
</script>
The height is the page's content: the example, and the panel when it shows. Content outside the page's flow isn't counted, like a dialog that <Teleport> moves, or an element positioned outside the example. An example whose height follows the viewport, in vh, grows with the <iframe>, so give it a fixed height instead.
Keep in mind what an embed does and doesn't do:
- It takes no props. An example sets its own props, so the URL holds none, and a component, which needs props, has no embed. The controls set props from inside the embed, and their values don't go in the URL, so a reload starts from "(default)".
- It takes one message at most. The colour mode, when its URL has
theme. The page that frames it can't select an example or set a prop. - Your host decides who may frame it. The site sets no
X-Frame-OptionsorContent-Security-Policy: frame-ancestors, so any page can frame it. To limit that, set one of those headers on your host.
The dev preview serves the same page, at embed.html beside its own URL, like http://127.0.0.1:5173/embed.html?example=examples/Card&target=vue. The page takes a free port on each run unless you set --port, so set it to keep a dev URL from one run to the next. Each target's server still takes a free port, which embed.html finds for you.
Deploy
The site is plain files, so any static host serves it. On Cloudflare, a Worker with static assets serves the directory, and Workers Builds builds it on every push and gives each pull request a preview URL. Add a script that builds it to your package.json:
"preview:build": "unframework preview build --out dist/preview",
Then point a wrangler.json at the directory:
{
"name": "my-components-preview",
"compatibility_date": "2026-11-01",
"assets": { "directory": "./dist/preview" },
"previews": {}
}
In the Worker's build settings, the build command is npm run preview:build, and the deploy command is npx wrangler deploy.
The decisions behind this page are ADR-0088, ADR-0110, ADR-0111, ADR-0112 and ADR-0113.