0
# Storybook UI
1

2
Storybook UI is the core React-based user interface library that provides the foundational rendering system for Storybook, a tool for developing UI components in isolation. It offers a minimal Provider API pattern where consumers extend a base Provider class to supply UI elements, API handling, and configuration for the Storybook manager interface.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import renderStorybookUI, { Provider, Root, RootProps } from "@storybook/ui";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const renderStorybookUI = require("@storybook/ui").default;
21
const { Provider, Root } = require("@storybook/ui");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import renderStorybookUI, { Provider } from "@storybook/ui";
28

29
// Extend the Provider base class
30
class MyProvider extends Provider {
31
  getElements(type) {
32
    // Return UI elements by type - must be implemented
33
    return {
34
      sidebar: { component: MySidebar },
35
      preview: { component: MyPreview },
36
      panel: { component: MyPanel }
37
    };
38
  }
39
  
40
  handleAPI(api) {
41
    // Handle API initialization - must be implemented
42
    console.log("API initialized:", api);
43
    api.setStories(this.stories);
44
  }
45
  
46
  getConfig() {
47
    // Return configuration object - optional with default empty implementation
48
    return {
49
      theme: "light",
50
      showNav: true
51
    };
52
  }
53
}
54

55
// Render the Storybook UI
56
const domNode = document.getElementById("root");
57
const provider = new MyProvider();
58
renderStorybookUI(domNode, provider);
59
```
60

61
## Architecture
62

63
Storybook UI implements a minimal provider pattern architecture:
64

65
- **Provider System**: Base Provider class that must be extended, requiring implementation of `getElements()` and `handleAPI()` methods
66
- **Root Component**: React component that wraps the entire Storybook UI with necessary providers (Helmet, Location, Theme)
67
- **Rendering Function**: Single entry point function that validates the provider and mounts the UI to a DOM node
68

69
The package has a very focused public API with only 4 exports, maintaining clear separation between public interface and internal implementation.
70

71
## Capabilities
72

73
### Core Rendering
74

75
Main function to render the Storybook UI into a DOM element using a configured provider.
76

77
```typescript { .api }
78
/**
79
 * Renders the Storybook UI into a DOM node using the provided provider
80
 * @param domNode - Target DOM element where the UI will be rendered
81
 * @param provider - Provider instance that extends the base Provider class
82
 * @throws Error if provider is not an instance of the Provider class
83
 */
84
function renderStorybookUI(domNode: HTMLElement, provider: Provider): void;
85
```
86

87
[Core Rendering](./core-rendering.md)
88

89
### Provider System
90

91
Base provider class and React components for building custom Storybook UI implementations.
92

93
```typescript { .api }
94
class Provider {
95
  /**
96
   * Get UI elements by type - must be implemented by subclasses
97
   * @param type - Type identifier for UI elements (from @storybook/addons Types enum)
98
   * @throws Error if not implemented by subclass
99
   */
100
  getElements(type: Types): any;
101
  
102
  /**
103
   * Handle API initialization - must be implemented by subclasses  
104
   * @param api - The Storybook API instance
105
   * @throws Error if not implemented by subclass
106
   */
107
  handleAPI(api: unknown): void;
108
  
109
  /**
110
   * Return configuration object - has default empty implementation
111
   * @returns Configuration object for the Storybook UI
112
   */
113
  getConfig(): any;
114
}
115

116
interface RootProps {
117
  /** Provider instance that supplies UI elements and configuration */
118
  provider: Provider;
119
  /** Optional browser history instance for routing (currently unused) */
120
  history?: History;
121
}
122

123
/**
124
 * Root React component that wraps the Storybook UI with necessary providers
125
 */
126
const Root: FunctionComponent<RootProps>;
127
```
128

129
[Provider System](./provider-system.md)
130

131
## Types
132

133
```typescript { .api }
134
type Types = 'TAB' | 'PANEL' | 'TOOL' | 'TOOLEXTRA' | 'PREVIEW' | 'NOTES_ELEMENT';
135

136
interface History {
137
  // Browser history interface for routing (optional parameter, currently unused in implementation)
138
  push(path: string): void;
139
  replace(path: string): void;
140
  go(delta: number): void;
141
  back(): void;
142
  forward(): void;
143
  listen(listener: Function): Function;
144
}
145
```