Registry / web-framework / storybook-addon-vue-slots

storybook-addon-vue-slots

library0.9.29jsnpmunverified

storybook-addon-vue-slots is a Storybook addon designed to enhance the development and documentation of Vue 3 components by providing robust support for defining and controlling component slots directly within Storybook stories. It simplifies the process of creating stories for components with complex or multiple slots, allowing developers to manage slot content via Storybook's controls interface and automatically generate relevant code snippets. The current stable version is `0.9.29`, with active development on `0.9.30-next.x` branches which include breaking changes for future Storybook versions. This addon addresses a common challenge in Vue component development by offering a structured and interactive way to visualize and test slot variations, distinguishing it from general Storybook Vue setups that might require manual template string manipulation for slots. It integrates into the Storybook ecosystem to provide a seamless workflow for Vue component libraries.

web-framework testing

npm install storybook-addon-vue-slots

github ↗package ↗

INSTALL

IMPORT

SIG · STORYBOOK-ADDON-VU

storybook-addon-vue-slots

web-frameworkjavascriptv0.9.29

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Storybook Addon Registration

✓ export default { addons: [ // ... other addons 'storybook-addon-vue-slots' ] } satisfies StorybookConfig;

✗ import { addon } from 'storybook-addon-vue-slots';

The addon is typically registered by its string name in the `addons` array within your `.storybook/main.ts` or `.storybook/main.js` file. There is no direct named import from the package for registration.

StorybookConfig

✓ import type { StorybookConfig } from '@storybook/vue3-vite';

✗ import { StorybookConfig } from '@storybook/vue3-vite';

Always use `import type` for type-only imports to ensure proper tree-shaking and avoid runtime issues in ESM environments. The specific framework import might vary (e.g., `@storybook/vue3` or `@storybook/vue3-vite`).

Slots Parameter

✓ export default meta = { parameters: { slots: { default: 'Default content', header: { template: '<h2>Header</h2>' } } } };

✗ export default meta = { slots: { // ... incorrect placement } };

Slot definitions are provided via the `parameters.slots` object within your story's `meta` configuration. This is how you inform the addon about the slot content.

This quickstart demonstrates how to set up `storybook-addon-vue-slots` to define and control both default and named slots for a Vue 3 component within Storybook. It includes the component, `main.ts` configuration, and a story file illustrating `parameters.slots` for static content and `argTypes`/`args` for dynamic control via Storybook's UI.

<template> <button class="my-button"> <slot name="icon" :size="iconSize">✨</slot> <slot>Default Button Text</slot> <slot name="footer"></slot> </button> </template> <script setup lang="ts"> import { ref } from 'vue'; const iconSize = ref('medium'); </script> <style scoped> .my-button { padding: 10px 20px; border: 1px solid #ccc; border-radius: 4px; background-color: #f0f0f0; cursor: pointer; } </style> // .storybook/main.ts import type { StorybookConfig } from '@storybook/vue3-vite'; const config: StorybookConfig = { stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ '@storybook/addon-essentials', 'storybook-addon-vue-slots' // Add the Vue Slots addon here ], framework: { name: '@storybook/vue3-vite', options: {}, }, }; export default config; // src/stories/MyButton.stories.ts import type { Meta, StoryObj } from '@storybook/vue3'; import MyButton from '../components/MyButton.vue'; const meta: Meta<typeof MyButton> = { component: MyButton, title: 'Components/MyButton', tags: ['autodocs'], parameters: { // Configure slots using the addon's parameters slots: { default: 'Click me!', icon: { template: '<span>🚀</span>' }, footer: { template: '<em>Hint: Press Alt+H for help.</em>' }, }, }, argTypes: { // Expose default slot content as an arg for control panel interaction default: { control: 'text', description: 'Content for the default slot', }, // Expose icon slot content as an arg icon: { control: 'text', description: 'Content for the named icon slot', }, }, args: { default: 'Dynamic Button Text', icon: '✨' }, }; export default meta; type Story = StoryObj<typeof meta>; export const Default: Story = {}; export const CustomIconAndFooter: Story = { parameters: { slots: { icon: { template: '<span style="font-size: 20px;">⭐</span>' }, footer: { template: '<small>Powered by Storybook</small>' }, }, }, args: { default: 'Submit', icon: '⭐' }, // Args for controls };

Debug

Known issues

breakingStarting with versions `0.9.30-next.x` (and planned for the next stable minor/major release), `storybook-addon-vue-slots` will drop CommonJS (CJS) support and become an ESM-only package. This will cause `ERR_REQUIRE_ESM` errors in projects still configured with CJS.

fix

Ensure your Storybook project and consuming application are configured to use ES Modules (ESM). Update your `.storybook/main.js` to `.storybook/main.ts` or `.storybook/main.js` to explicitly export as ESM, e.g., by adding `"type": "module"` to your `package.json` or ensuring all relevant files use `import`/`export` syntax. Storybook's `main.js|ts` file itself must be valid ESM.

affects: >=0.9.30-next.0

gotchaThis addon, like all Storybook addons, has specific peer dependencies on Storybook and Vue versions. Mismatched versions (e.g., using an older addon version with Storybook 8 or 9) can lead to unexpected behavior, rendering issues, or build failures.

fix

Always check the `peerDependencies` in the package's `package.json` or npm page and ensure your project's Storybook and Vue versions align. Upgrade Storybook and the addon in tandem, following their respective migration guides. Use `npx storybook@latest doctor` to identify common dependency issues.

affects: >=0.9.0

gotchaWhen defining complex slot content using `parameters.slots.slotName.template`, ensure the template string is valid Vue template syntax and correctly references `args` if dynamic content is intended. Incorrect syntax or missing `v-bind="args"` (or similar) on the component in the story's `render` function can prevent slot content from displaying or interacting as expected.

fix

Review the `parameters.slots` configuration. For dynamic content, use `{{ args.yourArgName }}` within the `template` string and ensure `yourArgName` is correctly defined in `argTypes` and `args` in your story. Test with simpler template strings first to isolate issues.

affects: >=0.9.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM is not defined in ES module scope

Attempting to `require()` the `storybook-addon-vue-slots` package (or a module that imports it) in a CommonJS context, while the package is now ESM-only in newer versions.

fix

Convert your project's Storybook configuration files (`.storybook/main.js`, `.storybook/preview.js`) to ES Modules. This typically involves using `import`/`export` syntax, ensuring your `package.json` specifies `"type": "module"` if necessary, and upgrading your build tools (e.g., Vite) to handle ESM correctly. For older projects, consider sticking to an older version of the addon that still supports CJS or performing a full migration to ESM.

Cannot find module 'storybook-addon-vue-slots' or its corresponding type declarations.

The package is not correctly installed or its entry point is not resolvable by your module resolver, often due to an ESM/CJS mismatch or incorrect `main.ts` configuration.

fix

First, ensure `storybook-addon-vue-slots` is installed as a dev dependency (`npm install -D storybook-addon-vue-slots`). Verify that your `tsconfig.json`'s `moduleResolution` option is set to a value that supports `"types"` conditions (e.g., `"bundler"` or `"node16"` for modern projects). For Storybook's `main.ts`, ensure the addon is correctly listed in the `addons` array as a string: `'storybook-addon-vue-slots'`. If upgrading from an older Storybook, ensure `main.ts` itself is ESM.

TypeError: Cannot read properties of undefined (reading 'slots')

The addon is not correctly registered in `.storybook/main.ts`, or the `parameters.slots` object is being accessed before it's defined or correctly processed by Storybook.

fix

Double-check your `.storybook/main.ts` file to ensure `'storybook-addon-vue-slots'` is present in the `addons` array. Verify that the `parameters.slots` object in your stories follows the correct structure as outlined in the addon's documentation. Clear Storybook cache and restart the development server.

Upgrade

Version history

0.9.29latest on npm

Audit

Dependencies

vuerequiredRequired for Vue 3 component rendering and reactivity.

reactrequiredPeer dependency for Storybook's internal UI framework, even when developing Vue components.

react-domrequiredPeer dependency for Storybook's internal UI framework.

@storybook/vue3requiredThe core Storybook framework adapter for Vue 3.

@storybook/typesrequiredProvides core Storybook TypeScript types for configuration.

@storybook/blocksrequiredPart of Storybook's documentation and rendering system.

@storybook/themingrequiredStorybook's theming capabilities.

@storybook/componentsrequiredStorybook's UI components.

@storybook/core-eventsrequiredStorybook's internal event system.

@storybook/preview-apirequiredAPI for Storybook's preview iframe environment.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/JoJk0/storybook-addon-vue-slots ↗

packagehttps://www.npmjs.com/package/storybook-addon-vue-slots ↗