Skip to content

Story ​

Create a story. Must be at the top level of the story file.

title ​

Title of the story.

vue
<template>
  <Story title="My story">
    Hello world
  </Story>
</template>

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.

vue
<template>
  <Story id="my-story">
    Hello world
  </Story>
</template>

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. Default true; false renders 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.vue: layout.iframe is not read by a grid layout, so it does nothing: use iframeGrid

A type other than 'single' or 'grid' is reported the same way.

Learn more

initState ​

Function that returns the initial state. Will be used as default value for variants.

vue
<script setup>
function initState() {
  return {
    disabled: false,
    content: 'Hello world'
  }
}
</script>

<template>
  <Story title="My Button" :init-state="initState">
    <template #default="{ state }">
      <button :disabled="state.disabled">
        {{ state.content }}
      </button>
    </template>
  </Story>
</template>

Learn more

setupApp ​

A function to configure the Vue application. This will be the default for the variants in the story.

It receives a payload object as parameter with the following properties:

  • app: The Vue application instance.
  • story: The story object.
  • variant: The variant object.
vue
<script setup>
function mySetupApp({ app, story, variant }) {
  app.provide('demo', 'meow')
}
</script>

<template>
  <Story :setup-app="mySetupApp">
    <!-- ... -->
  </Story>
</template>

Learn more

group ​

The id of a group to include the story in.

vue
<template>
  <Story group="my-group">
    Hello world
  </Story>
</template>

Learn more

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.

vue
<template>
  <Story icon="lucide:cpu">
    Hello world
  </Story>
</template>

iconColor ​

The icon color.

vue
<template>
  <Story icon-color="#8B5CF6">
    Hello world
  </Story>
</template>

docsOnly ​

This story will only render a documentation page.

vue
<template>
  <Story
    group="top"
    docs-only
    icon="carbon:bookmark"
  />
</template>

<docs lang="md">
# Welcome

This is a demo book using Vue 3.

---

Learn more about Poveste [here](https://poveste.dev/).
</docs>

source ​

The copyable source code of the story.

vue
<script setup>
const source = `<h1>Toto</h1>

<input
  v-model.number="count"
  type="number"
>`
</script>

<template>
  <Story :source="source">
    <!-- ... -->
  </Story>
</template>

responsiveDisabled ​

Disables the responsive menu, preview resize handles and makes the preview always fit the available space.

vue
<template>
  <Story responsive-disabled>
    <!-- ... -->
  </Story>
</template>

autoPropsDisabled ​

Disables the automatic detection of props of the components in the story.

vue
<template>
  <Story auto-props-disabled>
    <!-- ... -->
  </Story>
</template>

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.

vue
<template>
  <Story :auto-props="{ size: { control: 'select', options: ['sm', 'md', 'lg'] }, onClick: false }">
    <!-- ... -->
  </Story>
</template>

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.

vue
<template>
  <Story :auto-docs="['props', 'events']">
    <!-- ... -->
  </Story>
</template>

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.

vue
<template>
  <Story :a11y="{ disableRules: ['color-contrast'] }">
    <!-- ... -->
  </Story>
</template>

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:

vue
<script setup lang="ts">
import { SelectRoot, SelectTrigger } from '..'
import SelectDemo from './_SelectDemo.vue'
</script>

<template>
  <Story :component="[SelectRoot, SelectTrigger]">
    <SelectDemo />
  </Story>
</template>

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, such as a wrapper or 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 <Story> and <Variant>:

ts
declare module 'poveste' {
  interface CommonMeta {
    /** Set to `false` to render without the book's wrapper. */
    wrapper?: boolean
  }
}

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.

  • false hides the pane for this story, whatever the reader has set.
  • true shows it, whatever the reader has set.
  • Left out, the story follows the reader's setting, which starts on.
vue
<script lang="ts" setup>
const meta = { storyOptions: false }
</script>

<template>
  <Story
    title="Dashboard"
    :meta="meta"
  >
    <!-- ... -->
  </Story>
</template>

Use it for a story with nothing to adjust, where the pane only takes room from the preview. It works in books whose stories are written in Vue or Svelte. A Solid or React story cannot set meta yet (#1295).

Slot: controls ​

Content of the 'Controls' pane used to interact with the story. This will be the default content for variants of the story but you can override it by defining a controls slot in a variant.

Props:

  • state: Object with the current state of the variant (if you are using initState).
vue
<template>
  <Story>
    <template #controls="{ state }">
      <!-- Interact with state here -->
      {{ state }}
    </template>

    <Variant>
      <!-- Controls reused here -->
    </Variant>
  </Story>
</template>

Learn more

Released under the MIT License. Updates on Bluesky and X.