0
# Storybook HTML
1

2
Storybook HTML is a renderer specifically designed for developing, documenting, and testing HTML UI components in isolation within the Storybook environment. It provides a bridge between raw HTML/JavaScript components and Storybook's development ecosystem, enabling developers to create stories for vanilla HTML components without requiring a specific frontend framework.
3

4
## Package Information
5

6
- **Package Name**: @storybook/html
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/html`
10

11
## Core Imports
12

13
```typescript
14
import type { Meta, StoryObj, StoryFn, Decorator } from "@storybook/html";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Meta, StoryObj, StoryFn, Decorator } = require("@storybook/html");
21
```
22

23
For portable stories (testing and documentation):
24

25
```typescript
26
import { setProjectAnnotations } from "@storybook/html";
27
```
28

29
For advanced rendering capabilities:
30

31
```typescript
32
import { render, renderToCanvas, parameters, argTypesEnhancers } from "@storybook/html";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import type { Meta, StoryObj } from "@storybook/html";
39

40
// Define component metadata
41
const meta: Meta = {
42
  title: "Example/Button",
43
  parameters: {
44
    layout: "centered",
45
  },
46
  argTypes: {
47
    backgroundColor: { control: "color" },
48
    label: { control: "text" },
49
    size: {
50
      control: { type: "select" },
51
      options: ["small", "medium", "large"],
52
    },
53
  },
54
};
55

56
export default meta;
57
type Story = StoryObj;
58

59
// String template story
60
export const Primary: Story = {
61
  args: {
62
    label: "Button",
63
    backgroundColor: "#007bff",
64
  },
65
  render: ({ label, backgroundColor, ...args }) => {
66
    return `
67
      <button style="background-color: ${backgroundColor}; padding: 10px 20px; border: none; border-radius: 4px; color: white;">
68
        ${label}
69
      </button>
70
    `;
71
  },
72
};
73

74
// Function-based story
75
export const Interactive: Story = {
76
  args: {
77
    label: "Click Me",
78
  },
79
  render: ({ label, ...args }) => {
80
    const button = document.createElement("button");
81
    button.textContent = label;
82
    button.addEventListener("click", () => alert("Button clicked!"));
83
    return button;
84
  },
85
};
86
```
87

88
## Architecture
89

90
Storybook HTML is built around several key concepts:
91

92
- **Renderer System**: Handles different types of HTML content (strings, DOM nodes, functions)
93
- **Type Safety**: Full TypeScript integration for stories, decorators, and configuration
94
- **Template Interpolation**: String-based components support `{{arg}}` placeholder syntax
95
- **DOM Manipulation**: Direct HTMLElement support with attribute binding
96
- **Documentation Integration**: Automatic source code extraction for documentation
97
- **Portable Stories**: Testing and documentation utilities for component isolation
98

99
## Capabilities
100

101
### Story Types and Metadata
102

103
Core types for defining HTML stories with proper TypeScript support and Storybook integration.
104

105
```typescript { .api }
106
/**
107
 * Metadata to configure the stories for a component.
108
 */
109
type Meta<TArgs = Args> = ComponentAnnotations<HtmlRenderer, TArgs>;
110

111
/**
112
 * Story function that represents a CSFv2 component example.
113
 */
114
type StoryFn<TArgs = Args> = AnnotatedStoryFn<HtmlRenderer, TArgs>;
115

116
/**
117
 * Story object that represents a CSFv3 component example.
118
 */
119
type StoryObj<TArgs = Args> = StoryAnnotations<HtmlRenderer, TArgs>;
120

121
/**
122
 * Story decorator function type for HTML renderer.
123
 */
124
type Decorator<TArgs = StrictArgs> = DecoratorFunction<HtmlRenderer, TArgs>;
125

126
/**
127
 * Story loader function type for HTML renderer.
128
 */
129
type Loader<TArgs = StrictArgs> = LoaderFunction<HtmlRenderer, TArgs>;
130

131
/**
132
 * Story context type for HTML renderer.
133
 */
134
type StoryContext<TArgs = StrictArgs> = GenericStoryContext<HtmlRenderer, TArgs>;
135

136
/**
137
 * Project annotations type for HTML renderer.
138
 */
139
type Preview = ProjectAnnotations<HtmlRenderer>;
140
```
141

142
### Core Argument Types
143

144
Essential types for story arguments and configuration.
145

146
```typescript { .api }
147
/**
148
 * Generic arguments type for stories.
149
 */
150
type Args = Record<string, any>;
151

152
/**
153
 * Argument type definitions for controls and documentation.
154
 */
155
type ArgTypes = Record<string, ArgTypeDef>;
156

157
/**
158
 * Story parameters for configuration and metadata.
159
 */
160
type Parameters = Record<string, any>;
161

162
/**
163
 * Strictly typed arguments for enhanced type safety.
164
 */
165
type StrictArgs = Record<string, any>;
166
```
167

168
### HTML Renderer Interface
169

170
The core renderer interface that defines how HTML components are handled.
171

172
```typescript { .api }
173
interface HtmlRenderer extends WebRenderer {
174
  /**
175
   * The component can be a string template, HTMLElement, or story function.
176
   */
177
  component: string | HTMLElement | ArgsStoryFn<HtmlRenderer>;
178
  
179
  /**
180
   * The result returned by story functions - either HTML string or DOM node.
181
   */
182
  storyResult: StoryFnHtmlReturnType;
183
}
184

185
/**
186
 * Valid return types for HTML story functions.
187
 */
188
type StoryFnHtmlReturnType = string | Node;
189

190
/**
191
 * Error display arguments for story rendering failures.
192
 */
193
interface ShowErrorArgs {
194
  title: string;
195
  description: string;
196
}
197
```
198

199

200
### Portable Stories
201

202
Utilities for using stories outside of Storybook environment for testing and documentation.
203

204
```typescript { .api }
205
/**
206
 * Function that sets the globalConfig of your storybook for portable story usage.
207
 * Should be run once to apply global configuration (decorators, parameters) to stories.
208
 * 
209
 * @param projectAnnotations - Project configuration from .storybook/preview
210
 * @returns Normalized project annotations for HTML renderer
211
 */
212
function setProjectAnnotations(
213
  projectAnnotations: 
214
    | NamedOrDefaultProjectAnnotations<any>
215
    | NamedOrDefaultProjectAnnotations<any>[]
216
): NormalizedProjectAnnotations<HtmlRenderer>;
217
```
218

219
### Core Rendering Functions
220

221
Essential rendering functions that power the HTML renderer's story rendering capabilities.
222

223
```typescript { .api }
224
/**
225
 * Core story rendering function that handles different component types.
226
 * Processes string templates, HTMLElement instances, and function components.
227
 * 
228
 * @param args - Story arguments passed to the component
229
 * @param context - Story context containing metadata and configuration
230
 * @returns Rendered HTML string or DOM node
231
 */
232
function render(args: Args, context: StoryContext): StoryFnHtmlReturnType;
233

234
/**
235
 * Canvas rendering function that displays stories in the Storybook canvas.
236
 * Handles DOM manipulation and lifecycle events for story display.
237
 * 
238
 * @param renderContext - Rendering context with story function and callbacks
239
 * @param canvasElement - Target DOM element for rendering the story
240
 */
241
function renderToCanvas(
242
  renderContext: {
243
    storyFn: () => StoryFnHtmlReturnType;
244
    kind: string;
245
    name: string;
246
    showMain: () => void;
247
    showError: (args: ShowErrorArgs) => void;
248
    forceRemount: boolean;
249
  },
250
  canvasElement: HTMLElement
251
): void;
252
```
253

254
### Template Rendering
255

256
For string-based components, the renderer supports template interpolation:
257

258
```typescript
259
// Template with argument placeholders
260
export const TemplateExample: Story = {
261
  args: {
262
    title: "Hello World",
263
    content: "This is dynamic content",
264
  },
265
  render: () => `
266
    <div class="card">
267
      <h2>{{title}}</h2>
268
      <p>{{content}}</p>
269
    </div>
270
  `,
271
};
272
```
273

274
### HTMLElement Components
275

276
For DOM-based components, arguments are automatically applied as attributes:
277

278
```typescript
279
export const ElementExample: Story = {
280
  args: {
281
    "data-testid": "button",
282
    class: "primary",
283
  },
284
  render: () => {
285
    const button = document.createElement("button");
286
    button.textContent = "Click me";
287
    return button; // Arguments will be set as attributes
288
  },
289
};
290
```
291

292
### Function Components
293

294
For maximum flexibility, components can be functions that receive arguments and context:
295

296
```typescript
297
type ComponentFunction = (args: Args, context: StoryContext) => StoryFnHtmlReturnType;
298

299
export const FunctionExample: Story = {
300
  render: (args, context) => {
301
    const { label, onClick } = args;
302
    const button = document.createElement("button");
303
    button.textContent = label;
304
    button.addEventListener("click", onClick || (() => {}));
305
    return button;
306
  },
307
};
308
```
309

310
### Renderer Configuration
311

312
Default configuration and enhancement utilities for the HTML renderer.
313

314
```typescript { .api }
315
/**
316
 * Default parameters object for HTML renderer configuration.
317
 * Sets the renderer type to 'html' for proper Storybook integration.
318
 */
319
const parameters: {
320
  renderer: 'html';
321
};
322

323
/**
324
 * Array of argument type enhancers for improved story controls and documentation.
325
 * Automatically enhances argument types for better Storybook integration.
326
 */
327
const argTypesEnhancers: ArgTypesEnhancer[];
328
```
329

330
## Types
331

332
```typescript { .api }
333
/**
334
 * HTML renderer-specific parameters interface.
335
 */
336
interface Parameters {
337
  renderer: 'html';
338
  docs?: {
339
    story: { inline: boolean };
340
    source: {
341
      type: SourceType.DYNAMIC;
342
      language: 'html';
343
      code: any;
344
      excludeDecorators: any;
345
    };
346
  };
347
}
348

349
/**
350
 * Extended story context for HTML renderer with HTML-specific parameters.
351
 */
352
type StoryContext = DefaultStoryContext<HtmlRenderer> & {
353
  parameters: DefaultStoryContext<HtmlRenderer>['parameters'] & Parameters;
354
};
355
356
```