0
# Storybook Web Components
1

2
Storybook Web Components renderer enables developing, documenting, and testing UI components in isolation using the Storybook development environment. It provides specialized rendering capabilities for web component technologies including Lit and lit-html, offering integration capabilities for component development workflows with full TypeScript support.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For custom elements management:
18

19
```typescript
20
import { setCustomElements, getCustomElements } from "@storybook/web-components";
21
```
22

23
For rendering functions:
24

25
```typescript
26
import { render, renderToCanvas } from "@storybook/web-components";
27
```
28

29
For portable stories (testing):
30

31
```typescript
32
import { setProjectAnnotations } from "@storybook/web-components";
33
```
34

35
## Basic Usage
36

37
### Story Creation
38

39
```typescript
40
import type { Meta, StoryObj } from "@storybook/web-components";
41

42
// Component metadata
43
const meta: Meta = {
44
  title: "Example/Button",
45
  component: "my-button",
46
  parameters: {
47
    layout: "centered",
48
  },
49
  argTypes: {
50
    backgroundColor: { control: "color" },
51
  },
52
};
53

54
export default meta;
55
type Story = StoryObj;
56

57
// Story definition
58
export const Primary: Story = {
59
  args: {
60
    primary: true,
61
    label: "Button",
62
  },
63
};
64
```
65

66
### Custom Elements Integration
67

68
```typescript
69
import { setCustomElements } from "@storybook/web-components";
70
import customElements from "./custom-elements.json";
71

72
// Configure custom elements for documentation
73
setCustomElements(customElements);
74
```
75

76
## Architecture
77

78
Storybook Web Components renderer is built around several key components:
79

80
- **Type System**: TypeScript interfaces for type-safe story creation (`Meta`, `StoryFn`, `StoryObj`)
81
- **Framework Integration**: Functions for custom elements metadata management and validation
82
- **Testing Support**: Portable stories API for component testing outside Storybook
83

84
## Capabilities
85

86
### Story Creation & Types
87

88
Core TypeScript interfaces and types for creating type-safe Storybook stories for web components.
89

90
```typescript { .api }
91
type Meta<TArgs = Args> = ComponentAnnotations<WebComponentsRenderer, TArgs>;
92

93
type StoryFn<TArgs = Args> = AnnotatedStoryFn<WebComponentsRenderer, TArgs>;
94

95
type StoryObj<TArgs = Args> = StoryAnnotations<WebComponentsRenderer, TArgs>;
96

97
type Decorator<TArgs = StrictArgs> = DecoratorFunction<WebComponentsRenderer, TArgs>;
98

99
type Preview = ProjectAnnotations<WebComponentsRenderer>;
100

101
type Loader<TArgs = StrictArgs> = LoaderFunction<WebComponentsRenderer, TArgs>;
102

103
type StoryContext<TArgs = StrictArgs> = GenericStoryContext<WebComponentsRenderer, TArgs>;
104
```
105

106
[Story Creation & Types](./story-types.md)
107

108
### Framework Integration
109

110
Utility functions for managing custom elements metadata, component validation, and framework configuration.
111

112
```typescript { .api }
113
function setCustomElements(customElements: any): void;
114

115
function getCustomElements(): any;
116

117
function isValidComponent(tagName: string): boolean;
118

119
function isValidMetaData(customElements: any): boolean;
120

121
function setCustomElementsManifest(customElements: any): void;
122
```
123

124
[Framework Integration](./framework-integration.md)
125

126
### Story Rendering
127

128
Core rendering functions for converting story definitions into DOM elements.
129

130
```typescript { .api }
131
function render(
132
  storyFn: StoryFn<any>,
133
  context: StoryContext<any>
134
): string | Node | DocumentFragment | TemplateResult | SVGTemplateResult;
135

136
function renderToCanvas(
137
  content: StoryFnHtmlReturnType,
138
  canvasElement: HTMLElement
139
): void;
140
```
141

142
### Portable Stories
143

144
Testing utilities for using Storybook stories outside of the Storybook environment, particularly useful for unit testing and integration testing.
145

146
```typescript { .api }
147
function setProjectAnnotations(
148
  projectAnnotations: NamedOrDefaultProjectAnnotations<any> | NamedOrDefaultProjectAnnotations<any>[]
149
): NormalizedProjectAnnotations<WebComponentsRenderer>;
150
```
151

152
[Portable Stories](./portable-stories.md)
153

154
### Advanced Functions
155

156
Internal and advanced utility functions for custom elements metadata processing and documentation generation. These functions are primarily used by Storybook's documentation addon but can be useful for advanced integrations.
157

158
```typescript { .api }
159
function extractArgTypesFromElements(
160
  tagName: string, 
161
  customElements: any
162
): Record<string, any>;
163

164
function extractArgTypes(tagName: string): Record<string, any> | undefined;
165

166
function extractComponentDescription(tagName: string): string | undefined;
167
```
168

169
[Advanced Functions](./advanced-functions.md)
170

171

172
## Types
173

174
```typescript { .api }
175
interface WebComponentsRenderer extends WebRenderer {
176
  component: string;
177
  storyResult: StoryFnHtmlReturnType;
178
}
179

180
type StoryFnHtmlReturnType = 
181
  | string 
182
  | Node 
183
  | DocumentFragment 
184
  | TemplateResult 
185
  | SVGTemplateResult;
186

187
type Args = Record<string, any>;
188

189
type StrictArgs = Record<string, any>;
190

191
type ArgTypes = Record<string, any>;
192

193
type Parameters = Record<string, any>;
194

195
interface WebRenderer {
196
  name: string;
197
  render: (context: StoryContext) => any;
198
}
199

200
interface StoryContext<TArgs = StrictArgs> {
201
  id: string;
202
  title: string;
203
  kind: string;
204
  name: string;
205
  story: string;
206
  parameters: Parameters;
207
  args: TArgs;
208
  argTypes: ArgTypes;
209
  globals: Record<string, any>;
210
  hooks: any;
211
  loaded: Record<string, any>;
212
  viewMode: string;
213
}
214

215
type ComponentAnnotations<TRenderer, TArgs = Args> = {
216
  title?: string;
217
  component?: TRenderer['component'];
218
  parameters?: Parameters;
219
  argTypes?: ArgTypes;
220
  args?: Partial<TArgs>;
221
  decorators?: Decorator<TArgs>[];
222
  loaders?: Loader<TArgs>[];
223
  render?: StoryFn<TArgs>;
224
  subcomponents?: Record<string, TRenderer['component']>;
225
  tags?: string[];
226
};
227

228
type StoryAnnotations<TRenderer, TArgs = Args> = {
229
  args?: Partial<TArgs>;
230
  argTypes?: ArgTypes;
231
  parameters?: Parameters;
232
  decorators?: Decorator<TArgs>[];
233
  loaders?: Loader<TArgs>[];
234
  render?: StoryFn<TArgs>;
235
  play?: any;
236
  tags?: string[];
237
};
238

239
type AnnotatedStoryFn<TRenderer, TArgs = Args> = StoryFn<TArgs> & StoryAnnotations<TRenderer, TArgs>;
240

241
type ProjectAnnotations<TRenderer> = {
242
  parameters?: Parameters;
243
  argTypes?: ArgTypes;
244
  args?: Args;
245
  decorators?: Decorator[];
246
  loaders?: Loader[];
247
  render?: StoryFn;
248
  globalTypes?: Record<string, any>;
249
  tags?: string[];
250
};
251

252
type NamedOrDefaultProjectAnnotations<TRenderer> = 
253
  | ProjectAnnotations<TRenderer>
254
  | { default: ProjectAnnotations<TRenderer> };
255

256
type NormalizedProjectAnnotations<TRenderer> = ProjectAnnotations<TRenderer> & {
257
  normalizedParameters: Parameters;
258
  normalizedArgTypes: ArgTypes;
259
  normalizedArgs: Args;
260
};
261
```