Hst.Story
Create a story. Must be at the top level of the story file.
title
Title of the story.
<Hst.Story title="My story">
Hello world
</Hst.Story>id
Id of the story used in the URL. By default, the id is automatically generated from the file path. Setting an id manually will ensure the URL parameter doesn't change with the order of the variants in the story.
<Hst.Story id="my-story">
Hello world
</Hst.Story>layout
Layout of the story. Object with the following properties:
type:'single'or'grid'- with
type: 'single'you can specify:iframe: Whether to isolate the story in an iframe. You might want to disable it if you want to pass complex parameters that can't be serialized.
- with
type: 'grid'you can specify:width: Column size. Can be number (pixels) or string (like'100%').iframeGrid: Whether each grid item renders in an iframe of its own. Defaulttrue;falserenders the items in the app's document. See Grid iframes.
- with either type:
isolate: Give every render of the story a fresh sandbox document instead of a reused one. For stories that leave JavaScript state behind (patched globals, leaked timers) that the next story must not see.
A key the layout's type does not read is ignored, and poveste dev and poveste build say so when they collect the story. iframe belongs to a single layout and iframeGrid to a grid, so the usual case is one written on the other:
⚠️ …/src/Button.story.svelte: layout.iframe is not read by a grid layout, so it does nothing: use iframeGridA type other than 'single' or 'grid' is reported the same way.
initState
A function returning the initial state for the variant. Poveste owns this state, and passes it to the children and controls snippets — it is how controls reach your component.
<script>
const { Hst } = $props()
const initState = () => ({ disabled: false })
</script>
<Hst.Story {initState}>
{#snippet children({ state })}
<MyButton disabled={state.disabled} />
{/snippet}
{#snippet controls({ state })}
<Hst.Checkbox bind:value={state.disabled} title="Disabled" />
{/snippet}
</Hst.Story>A function rather than an object, because every variant gets its own copy.
State cannot live in a component-local let: Poveste mounts the story once per slot, so such a variable exists twice and a control writes to a different copy than your markup reads. A story with a controls slot and no initState logs an error saying so. See State & Controls and, if you are coming from histoire, the migration note.
setupApp
A function that runs before the story mounts, called after the global setup hook with the same argument.
It receives a payload object with the following properties:
story: The story object.variant: The variant object.setContext: Puts a value in the context the story mounts with.addWrapper: Adds a component that renders around the story.
<script>
const { Hst } = $props()
function setupApp({ variant }) {
document.body.dataset.variant = variant.title
}
</script>
<Hst.Story title="Story setup" {setupApp}>
<MyComponent />
</Hst.Story>It runs when a variant renders, so variant is always set. The setup file's setupSvelte also runs once with no variant, for the mount that fills the controls panel, which is why the meta example checks for one. Every variant inherits it, including explicit <Hst.Variant> children. A setupApp on the variant overrides it for that variant.
group
The id of a group to include the story in.
<Hst.Story group="my-group">
Hello world
</Hst.Story>icon
An Iconify id to customize the story icon in the tree.
The icon's data ships with the book when the book has its collection installed: @iconify-json/lucide for lucide:cpu, as a dev dependency. That holds for poveste build and poveste dev. Without the package, the icon loads from api.iconify.design when it first shows, so it is missing offline, and each reader's browser asks Iconify for it. The same goes for a variant's icon.
<Hst.Story icon="lucide:cpu">
Hello world
</Hst.Story>iconColor
The icon color.
<Hst.Story iconColor="#8B5CF6">
Hello world
</Hst.Story>docsOnly
This story will only render a documentation page — no preview, no controls, no variants.
Write the content in a sibling markdown file. Svelte has no <docs> block; a story file named MarkdownLinks.story.svelte takes its documentation from MarkdownLinks.story.md next to it.
<script>
const { Hst } = $props()
</script>
<Hst.Story group="top" docsOnly icon="carbon:bookmark" />A story file that renders nothing else is the whole component. If the page has no story to attach to at all, you can drop the .svelte file entirely and leave just the .story.md — see Documentation.
source
The copyable source code of the story.
<script>
const { Hst } = $props()
const source = `<h1>Toto</h1>
<input
bind:value={count}
type="number"
>`
</script>
<Hst.Story {source}>
<!-- ... -->
</Hst.Story>responsiveDisabled
Disables the responsive menu, preview resize handles and makes the preview always fit the available space.
<Hst.Story responsiveDisabled>
<!-- ... -->
</Hst.Story>Every variant inherits it. A variant sets responsiveDisabled={false} to opt out of what the story declared.
autoPropsDisabled
Turns off automatic prop detection for the story.
Poveste reads the props a component declares and builds a control for each one, so a variant that renders a component needs nothing written for it to be adjustable:
<Hst.Variant title="Naked">
<Button />
</Hst.Variant>The controls panel lists Button's props, and editing one re-renders the component with the new value. A prop the story binds itself keeps its own value until that control is used:
<Hst.Variant title="State" {initState}>
{#snippet children({ state })}
<Button label={state.label} />
{/snippet}
</Hst.Variant>Set autoPropsDisabled to stop this for every variant in the story:
<Hst.Story autoPropsDisabled>
<!-- ... -->
</Hst.Story>How it works, and what it needs
Vue reads props off the vnodes a variant is about to render. A Svelte component renders straight to the DOM, so there is no such tree — Poveste reads the props out of the component's own source when the book is built, and gives each component in a variant the values its controls hold (#233).
That means it covers components the story imports and renders directly. A component behind {#if} or {#each}, or one reached through <svelte:component>, is skipped — which component renders is only known once the story runs, and a control pointed at the wrong one is worse than no control. The variant's other components keep their controls.
A story that declares a variant inside {#if}, {#each} or {#await} gets no auto-props at all. Those variants are registered in an order nothing can predict before the story runs, so the whole story is left alone rather than risk driving the wrong one.
autoProps
Overrides or hides the automatic control of a prop, by the prop's name, for every variant in the story that doesn't set its own. A variant's autoProps replaces the story's whole. What each value does is in Override or hide a control.
<Hst.Story autoProps={{ size: { control: 'select', options: ['sm', 'md', 'lg'] }, onclick: false }}>
<!-- ... -->
</Hst.Story>autoDocs
The auto-docs table on this story's Docs tab, when the book's autoDocs is on. false shows none, and the story's components are never read for it, in dev or in a build. A list shows only the sections it names, in the table's own order: props, slots, events. A component with nothing in those sections gets no table. Left out, the story shows the whole table.
<Hst.Story autoDocs={['props', 'events']}>
<!-- ... -->
</Hst.Story>It belongs to the story, not to a variant: the table lists the components the story imports.
a11y
The accessibility check on this story's A11y tab. disableRules names axe-core rules to skip for this story's variants, on top of the book's own a11y.disableRules.
<Hst.Story a11y={{ disableRules: ['color-contrast'] }}>
<!-- ... -->
</Hst.Story>It belongs to the story, not to a variant.
component
The component, or a list of them, that this story's Docs tab documents, in place of the components it imports. Use it when the story renders a helper that wraps what it shows:
<script lang="ts">
import { SelectRoot, SelectTrigger } from '..'
import SelectDemo from './_SelectDemo.svelte'
const { Hst } = $props()
</script>
<Hst.Story component={[SelectRoot, SelectTrigger]}>
<SelectDemo />
</Hst.Story>Auto-docs reads it from the story's source, so name components the story imports, or members of a namespace it imports (Select.Root). A named component that can't be traced to a file gets no table, and poveste dev says why.
meta
StoryMeta, an object of your own keys plus storyOptions.
Free-form data attached to the story. meta is the book's to extend: put any key in it and read it back where your own code is handed the story, which in a Svelte book is the setup function. Poveste itself reads one key, storyOptions, described below. It also writes one of its own, hasVariantChildComponents, so leave that name alone.
In a TypeScript book, declare your keys once, in the setup file for instance. CommonMeta types meta on both Hst.Story and Hst.Variant:
declare module 'poveste' {
interface CommonMeta {
/** Read by the book's own setup function. */
theme?: 'light' | 'dark'
}
}The setup function is handed the story and the variant, so that is where a key is read. A variant's meta and its story's are separate objects. The function also runs once with no variant, for the mount that fills the controls panel, in the same document:
// src/poveste.setup.ts
import { defineSetupSvelte } from '@poveste/plugin-svelte'
export const setupSvelte = defineSetupSvelte(({ story, variant }) => {
if (!variant) {
return
}
document.documentElement.dataset.theme = variant.meta?.theme ?? story?.meta?.theme ?? 'light'
})meta.storyOptions
Overrides the Story Options switch in the Layout menu, for this story only. The pane that switch shows and hides is the one beside or below the preview, with the story's controls, docs, events and source.
falsehides the pane for this story, whatever the reader has set.trueshows it, whatever the reader has set.- Left out, the story follows the reader's setting, which starts on.
<Hst.Story title="Dashboard" meta={{ storyOptions: false }}>
<!-- ... -->
</Hst.Story>Use it for a story with nothing to adjust, where the pane only takes room from the preview. In a Svelte book it needs Poveste 0.19.0 or later: earlier versions dropped a story's meta, so the key did nothing (#1206).
Snippet: controls
Content of the 'Controls' pane used to interact with the story, passed as a controls snippet that receives the state. This will be the default content for variants of the story but you can override it by defining a controls snippet in a variant.
<Hst.Story>
{#snippet controls({ state })}
<Hst.Text bind:value={state.label} title="Label" />
{/snippet}
<Hst.Variant>
<!-- Controls reused here -->
</Hst.Variant>
</Hst.Story>