0
# Storybook for Angular
1

2
Storybook for Angular is a comprehensive framework integration that enables Angular developers to build, develop, document, and test UI components in isolation. It provides seamless integration with Angular's build system, modern Angular features, and the broader Storybook ecosystem.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Meta, StoryObj, moduleMetadata, applicationConfig } from "@storybook/angular";
15
import { argsToTemplate } from "@storybook/angular";
16
```
17

18
For decorators and utilities:
19

20
```typescript
21
import { 
22
  moduleMetadata, 
23
  componentWrapperDecorator, 
24
  applicationConfig 
25
} from "@storybook/angular";
26
```
27

28
## Basic Usage
29

30
```typescript
31
import type { Meta, StoryObj } from "@storybook/angular";
32
import { moduleMetadata } from "@storybook/angular";
33
import { ButtonComponent } from "./button.component";
34
import { CommonModule } from "@angular/common";
35

36
const meta: Meta<ButtonComponent> = {
37
  title: "Example/Button",
38
  component: ButtonComponent,
39
  decorators: [
40
    moduleMetadata({
41
      imports: [CommonModule],
42
    }),
43
  ],
44
  parameters: {
45
    layout: "centered",
46
  },
47
  tags: ["autodocs"],
48
  argTypes: {
49
    backgroundColor: { control: "color" },
50
  },
51
};
52

53
export default meta;
54
type Story = StoryObj<meta>;
55

56
export const Primary: Story = {
57
  args: {
58
    primary: true,
59
    label: "Button",
60
  },
61
};
62

63
export const Secondary: Story = {
64
  args: {
65
    label: "Button",
66
  },
67
};
68
```
69

70
## Architecture
71

72
Storybook for Angular is built around several key components:
73

74
- **Framework Integration**: Deep integration with Angular's build system through webpack5 and Angular CLI
75
- **Story System**: Component Story Format (CSF) v2/v3 support with Angular-specific types
76
- **Decorator Pattern**: Angular-specific decorators for module metadata, application config, and component wrapping
77
- **Template System**: Automatic template generation and customization utilities
78
- **Build Tools**: Angular CLI builders for development and production builds
79
- **Type System**: Full TypeScript integration with Angular-specific type transformations
80

81
## Capabilities
82

83
### Story Definition and Types
84

85
Core types and interfaces for defining Angular component stories using Component Story Format (CSF) v2 and v3.
86

87
```typescript { .api }
88
type Meta<TArgs = Args> = ComponentAnnotations<AngularRenderer, TransformComponentType<TArgs>>;
89
type StoryFn<TArgs = Args> = AnnotatedStoryFn<AngularRenderer, TransformComponentType<TArgs>>;
90
type StoryObj<TArgs = Args> = StoryAnnotations<AngularRenderer, TransformComponentType<TArgs>>;
91
type Decorator<TArgs = StrictArgs> = DecoratorFunction<AngularRenderer, TArgs>;
92
type Preview = ProjectAnnotations<AngularRenderer>;
93
```
94

95
[Story Definition and Types](./story-types.md)
96

97
### Angular Decorators
98

99
Angular-specific decorators for configuring module metadata, application configuration, and component wrapping in stories.
100

101
```typescript { .api }
102
declare function moduleMetadata<TArgs = any>(
103
  metadata: Partial<NgModuleMetadata>
104
): DecoratorFunction<AngularRenderer, TArgs>;
105

106
declare function applicationConfig<TArgs = any>(
107
  config: ApplicationConfig
108
): DecoratorFunction<AngularRenderer, TArgs>;
109

110
declare function componentWrapperDecorator<TArgs = any>(
111
  element: Type<unknown> | ((story: string) => string),
112
  props?: ICollection | ((storyContext: StoryContext<AngularRenderer, TArgs>) => ICollection)
113
): DecoratorFunction<AngularRenderer, TArgs>;
114
```
115

116
[Angular Decorators](./decorators.md)
117

118
### Template Utilities
119

120
Utilities for converting story arguments to Angular template bindings and handling dynamic template generation.
121

122
```typescript { .api }
123
declare function argsToTemplate<A extends Record<string, any>>(
124
  args: A,
125
  options?: ArgsToTemplateOptions<keyof A>
126
): string;
127

128
interface ArgsToTemplateOptions<T> {
129
  include?: Array<T>;
130
  exclude?: Array<T>;
131
}
132
```
133

134
[Template Utilities](./template-utilities.md)
135

136
### Angular CLI Builders
137

138
Angular CLI builders for starting and building Storybook applications integrated with Angular's build system.
139

140
```typescript { .api }
141
type StorybookBuilderOptions = JsonObject & {
142
  browserTarget?: string | null;
143
  tsConfig?: string;
144
  compodoc: boolean;
145
  enableProdMode?: boolean;
146
  styles?: StyleElement[];
147
  assets?: AssetPattern[];
148
} & Pick<CLIOptions, 'port' | 'host' | 'configDir' | 'quiet' | 'disableTelemetry'>;
149
```
150

151
[Angular CLI Builders](./cli-builders.md)
152

153
### Framework Configuration
154

155
Framework-specific configuration options and Storybook main configuration utilities for Angular projects.
156

157
```typescript { .api }
158
interface StorybookConfig extends StorybookConfigBase, StorybookConfigWebpack {
159
  framework: '@storybook/angular' | {
160
    name: '@storybook/angular';
161
    options: FrameworkOptions;
162
  };
163
}
164

165
interface FrameworkOptions extends AngularOptions {
166
  builder?: BuilderOptions;
167
}
168

169
declare function defineMain(config: StorybookConfig): StorybookConfig;
170
```
171

172
[Framework Configuration](./framework-config.md)
173

174
### Portable Stories
175

176
Utilities for using Storybook stories outside of the Storybook environment, such as in testing frameworks.
177

178
```typescript { .api }
179
declare function setProjectAnnotations(
180
  projectAnnotations: NamedOrDefaultProjectAnnotations<any> | NamedOrDefaultProjectAnnotations<any>[]
181
): NormalizedProjectAnnotations<AngularRenderer>;
182
```
183

184
[Portable Stories](./portable-stories.md)
185

186
## Types
187

188
### Core Interfaces
189

190
```typescript { .api }
191
interface AngularRenderer extends WebRenderer {
192
  component: any;
193
  storyResult: StoryFnAngularReturnType;
194
}
195

196
interface StoryFnAngularReturnType {
197
  props?: ICollection;
198
  moduleMetadata?: NgModuleMetadata;
199
  applicationConfig?: ApplicationConfig;
200
  template?: string;
201
  styles?: string[];
202
  userDefinedTemplate?: boolean;
203
}
204

205
interface NgModuleMetadata {
206
  declarations?: any[];
207
  entryComponents?: any[];
208
  imports?: any[];
209
  schemas?: any[];
210
  providers?: Provider[];
211
}
212

213
interface ICollection {
214
  [p: string]: any;
215
}
216
```
217

218
### Configuration Types
219

220
```typescript { .api }
221
interface AngularOptions {
222
  enableIvy?: boolean;
223
}
224

225
type Parameters = DefaultParameters & {
226
  bootstrapModuleOptions?: unknown;
227
};
228

229
type StoryContext = DefaultStoryContext<AngularRenderer> & { parameters: Parameters };
230
```