0
# Vue Rendering System
1

2
Core rendering functionality that handles Vue component mounting, lifecycle management, and DOM integration within the Storybook environment.
3

4
## Capabilities
5

6
### Render Function
7

8
Default Vue story render function that creates Vue component instances with proper args and context handling.
9

10
```typescript { .api }
11
/**
12
 * Default Vue story render function
13
 * @param args - Story arguments passed to the component
14
 * @param context - Story context containing component and metadata
15
 * @returns Vue component definition for rendering
16
 */
17
function render(args: Args, context: StoryContext): VueRenderer['storyResult'];
18

19
interface StoryContext<TArgs = StrictArgs> extends GenericStoryContext<VueRenderer, TArgs> {
20
  id: string;
21
  component: VueRenderer['component'];
22
  argTypes: StrictArgTypes;
23
}
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import { render } from "@storybook/vue";
30
import type { Meta, StoryObj } from "@storybook/vue";
31
import MyButton from "./MyButton.vue";
32

33
const meta: Meta<typeof MyButton> = {
34
  title: "Example/Button",
35
  component: MyButton,
36
  render, // Use custom render function
37
};
38

39
export default meta;
40

41
export const CustomRender: StoryObj<typeof meta> = {
42
  render: (args, context) => {
43
    return {
44
      components: { MyButton },
45
      setup() {
46
        return { args };
47
      },
48
      template: `
49
        <div style="padding: 20px;">
50
          <MyButton v-bind="args" />
51
        </div>
52
      `,
53
    };
54
  },
55
  args: {
56
    label: "Custom Rendered Button",
57
  },
58
};
59
```
60

61
### Render To Canvas
62

63
Renders a story to the DOM canvas element, handling Vue component mounting and lifecycle.
64

65
```typescript { .api }
66
/**
67
 * Render story to DOM canvas element
68
 * @param renderContext - Context containing story function and display handlers
69
 * @param canvasElement - DOM element to render the story into
70
 */
71
function renderToCanvas(
72
  renderContext: RenderContext<VueRenderer>,
73
  canvasElement: VueRenderer['canvasElement']
74
): void;
75

76
interface RenderContext<TRenderer extends Renderer> {
77
  title: string;
78
  name: string;
79
  storyFn: LegacyStoryFn<TRenderer>;
80
  showMain: () => void;
81
  showError: (args: ShowErrorArgs) => void;
82
  showException: (err: Error) => void;
83
  forceRemount: boolean;
84
}
85
```
86

87
### Renderer Constants
88

89
Constants used internally by the rendering system for component data management.
90

91
```typescript { .api }
92
/**
93
 * Vue component data key for storing the active component
94
 */
95
const COMPONENT = 'STORYBOOK_COMPONENT';
96

97
/**
98
 * Vue data key for storing component prop values
99
 */
100
const VALUES = 'STORYBOOK_VALUES';
101

102
/**
103
 * Alias for decorateStory function (used in preview entry)
104
 */
105
function applyDecorators(
106
  storyFn: LegacyStoryFn<VueRenderer>,
107
  decorators: DecoratorFunction<VueRenderer>[]
108
): LegacyStoryFn<VueRenderer>;
109
```
110

111
## Internal Rendering Details
112

113
### Component Instance Management
114

115
The renderer maintains a map of canvas elements to Vue instances for efficient re-rendering:
116

117
```typescript
118
// Internal implementation details (not part of public API)
119
const map = new Map<VueRenderer['canvasElement'], VueInstance>();
120

121
function getRoot(canvasElement: VueRenderer['canvasElement']): VueInstance {
122
  // Returns cached or creates new Vue instance
123
}
124
```
125

126
### Automatic Component Wrapping
127

128
The render function automatically creates wrapper components that handle:
129

130
- **Props Binding**: Automatic binding of story args to component props
131
- **Event Handling**: Automatic event listener setup for component events
132
- **Template Generation**: Dynamic template creation based on component structure
133
- **Reserved Tag Handling**: Automatic prefixing of reserved HTML tag names
134

135
**Example of Generated Template:**
136
```typescript
137
// For a component named MyButton with events
138
template: `<MyButton @click="$props['onClick']" v-bind="filterOutEventProps($props)" />`
139
```
140

141
### Error Handling
142

143
The rendering system provides comprehensive error handling:
144

145
```typescript { .api }
146
interface ShowErrorArgs {
147
  title: string;
148
  description: string;
149
}
150
```
151

152
**Common Error Scenarios:**
153
- Missing component annotation
154
- Invalid component names
155
- Template rendering failures
156
- Vue instance mounting errors
157

158
**Usage Example:**
159
```typescript
160
// Error handling in custom render function
161
export const ErrorExample: StoryObj = {
162
  render: (args, context) => {
163
    if (!context.component) {
164
      throw new Error(`Component missing for story ${context.id}`);
165
    }
166
    
167
    return {
168
      components: { MyComponent: context.component },
169
      template: '<MyComponent v-bind="args" />',
170
      setup() {
171
        return { args };
172
      },
173
    };
174
  },
175
};
176
```
177

178
### Hot Module Replacement
179

180
The rendering system supports hot module replacement for efficient development workflows:
181

182
```typescript
183
// HMR handling (internal)
184
if (typeof module !== 'undefined') {
185
  module?.hot?.decline(); // Stop HMR propagation
186
}
187
```
188

189
### Canvas Management
190

191
Vue 2.x mount behavior requires special canvas management:
192

193
- Creates child elements for mounting (Vue 2 replaces mount targets)
194
- Preserves canvas element references for play functions
195
- Handles component lifecycle during story switching
196
- Manages cleanup when stories unmount