0
# OWL (Odoo Web Library)
1

2
OWL is a modern, lightweight TypeScript UI framework built by Odoo for creating reactive web applications. It combines the best ideas from React and Vue in a simple and consistent way, featuring declarative components with ES6 classes and XML templates, fine-grained reactivity, hooks, and virtual DOM rendering.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { App, Component, mount, xml } from "@odoo/owl";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { App, Component, mount, xml } = require("@odoo/owl");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { App, Component, xml, useState } from "@odoo/owl";
27

28
class Counter extends Component {
29
  static template = xml`
30
    <div>
31
      <p>Count: <t t-esc="state.count"/></p>
32
      <button t-on-click="increment">+</button>
33
      <button t-on-click="decrement">-</button>
34
    </div>
35
  `;
36

37
  setup() {
38
    this.state = useState({ count: 0 });
39
  }
40

41
  increment() {
42
    this.state.count++;
43
  }
44

45
  decrement() {
46
    this.state.count--;
47
  }
48
}
49

50
const app = new App(Counter);
51
app.mount(document.body);
52
```
53

54
## Architecture
55

56
OWL is built around several key components:
57

58
- **App System**: Application container managing component lifecycle and mounting
59
- **Component Framework**: ES6 class-based components with templates and lifecycle hooks
60
- **Reactivity System**: Fine-grained reactive state management with automatic UI updates
61
- **Template System**: XML-based templates with compilation and runtime evaluation
62
- **BlockDOM**: Virtual DOM implementation optimized for template-driven rendering
63
- **Hook System**: Function-based utilities for state, effects, and component integration
64

65
## Capabilities
66

67
### Application & Component Framework
68

69
Core application container and component system for creating and managing OWL applications with mounting, lifecycle, and component hierarchy.
70

71
```typescript { .api }
72
class App<T, P, E> {
73
  constructor(Root: ComponentConstructor<P, E>, config?: AppConfig<P, E>);
74
  mount(target: HTMLElement | ShadowRoot, options?: { position?: "first-child" | "last-child" }): Promise<Component<P, E>>;
75
}
76

77
function mount<P, E>(
78
  C: ComponentConstructor<P, E>,
79
  target: HTMLElement | ShadowRoot,
80
  config?: AppConfig<P, E>
81
): Promise<Component<P, E>>;
82

83
class Component<Props = any, Env = any> {
84
  static template: string;
85
  static props?: Schema;
86
  static defaultProps?: any;
87
  constructor(props: Props, env: Env, node: ComponentNode);
88
  setup(): void;
89
  render(deep?: boolean): void;
90
}
91
```
92

93
[Application & Components](./app-components.md)
94

95
### Component Hooks
96

97
Hook functions for component state management, lifecycle integration, and accessing component context and environment.
98

99
```typescript { .api }
100
function useState<T>(state: T): T;
101
function useComponent(): Component;
102
function useRef<T extends HTMLElement>(name: string): { el: T | null };
103
function useEnv<E>(): E;
104
function useSubEnv(envExtension: Env): void;
105
function useChildSubEnv(envExtension: Env): void;
106
function useEffect<T extends unknown[]>(
107
  effect: (...dependencies: T) => void | (() => void),
108
  computeDependencies?: () => [...T]
109
): void;
110
function useExternalListener(
111
  target: EventTarget,
112
  eventName: string,
113
  handler: EventListener,
114
  eventParams?: AddEventListenerOptions
115
): void;
116
```
117

118
[Component Hooks](./hooks.md)
119

120
### Lifecycle Hooks
121

122
Component lifecycle management hooks for handling mounting, updating, rendering, and cleanup operations.
123

124
```typescript { .api }
125
function onWillStart(callback: () => void | Promise<void>): void;
126
function onMounted(callback: () => void): void;
127
function onWillUpdateProps(callback: (nextProps: any) => void | Promise<void>): void;
128
function onWillRender(callback: () => void): void;
129
function onRendered(callback: () => void): void;
130
function onWillPatch(callback: () => void): void;
131
function onPatched(callback: () => void): void;
132
function onWillUnmount(callback: () => void): void;
133
function onWillDestroy(callback: () => void): void;
134
function onError(callback: (error: Error) => void): void;
135
```
136

137
[Lifecycle Hooks](./lifecycle.md)
138

139
### Reactivity System
140

141
Fine-grained reactivity system for creating reactive state with automatic UI updates and change tracking.
142

143
```typescript { .api }
144
function reactive<T extends object>(target: T): T;
145
function markRaw<T extends object>(target: T): T;
146
function toRaw<T>(observed: T): T;
147
```
148

149
[Reactivity](./reactivity.md)
150

151
### Template System
152

153
XML-based template system with compilation, runtime evaluation, and template management for component rendering.
154

155
```typescript { .api }
156
function xml(...args: Parameters<typeof String.raw>): string;
157
```
158

159
[Templates](./templates.md)
160

161
### BlockDOM System
162

163
Virtual DOM implementation with block-based rendering, patching, and lifecycle management optimized for template-driven UIs.
164

165
```typescript { .api }
166
const blockDom: {
167
  mount: (vnode: VNode, fixture: HTMLElement, afterNode?: Node) => void;
168
  patch: (vnode1: VNode, vnode2: VNode, withBeforeRemove?: boolean) => void;
169
  remove: (vnode: VNode, withBeforeRemove?: boolean) => void;
170
  list: (items: any[], template: Function) => VNode;
171
  multi: (blocks: VNode[]) => VNode;
172
  text: (value: string) => VNode;
173
  comment: (value: string) => VNode;
174
  toggler: (condition: boolean, template: Function) => VNode;
175
  createBlock: (template: Function) => VNode;
176
  html: (htmlString: string) => VNode;
177
};
178
```
179

180
[BlockDOM](./blockdom.md)
181

182
### Utilities & Validation
183

184
Utility functions for event handling, DOM manipulation, data loading, and component validation.
185

186
```typescript { .api }
187
function batched(callback: () => void): () => void;
188
class EventBus extends EventTarget {
189
  trigger(name: string, payload?: any): void;
190
}
191
function htmlEscape(str: string): string;
192
function whenReady(callback: Function): void;
193
function loadFile(url: string): Promise<string>;
194
function markup(template: TemplateStringsArray, ...args: any[]): string;
195

196
function validate(obj: { [key: string]: any }, spec: Schema): void;
197
function validateType(key: string, value: any, descr: TypeDescription): string | null;
198
```
199

200
[Utilities & Validation](./utils-validation.md)
201

202
### Component Status
203

204
Component status checking utilities for debugging and lifecycle management.
205

206
```typescript { .api }
207
function status(component: Component): "new" | "mounted" | "cancelled" | "destroyed";
208
```
209

210
### Runtime Information
211

212
Runtime information about the OWL framework version and metadata.
213

214
```typescript { .api }
215
const __info__: {
216
  version: string;
217
};
218
```
219

220
## Types
221

222
### Core Types
223

224
```typescript { .api }
225
interface ComponentConstructor<P extends Props = any, E = any> {
226
  new (props: P, env: E, node: ComponentNode): Component<P, E>;
227
  template: string;
228
  defaultProps?: any;
229
  props?: Schema;
230
  components?: { [componentName: string]: ComponentConstructor };
231
}
232

233
type Props = { [key: string]: any };
234

235
interface Env {
236
  [key: string]: any;
237
}
238

239
interface AppConfig<P, E> {
240
  name?: string;
241
  test?: boolean;
242
  warnIfNoStaticProps?: boolean;
243
  props?: P;
244
  env?: E;
245
  dev?: boolean;
246
  translatableAttributes?: string[];
247
  translateFn?: (s: string, translationCtx: string) => string;
248
  templates?: string | Document | Record<string, string>;
249
  getTemplate?: (s: string) => Element | Function | string | void;
250
}
251
```
252

253
### Template Types
254

255
```typescript { .api }
256
type Template = (context: any, vnode: any, key?: string) => BDom;
257
```
258

259
### BlockDOM Types
260

261
```typescript { .api }
262
interface VNode<T = any> {
263
  mount(parent: HTMLElement, afterNode: Node | null): void;
264
  moveBeforeDOMNode(node: Node | null, parent?: HTMLElement): void;
265
  moveBeforeVNode(other: T | null, afterNode: Node | null): void;
266
  patch(other: T, withBeforeRemove: boolean): void;
267
  beforeRemove(): void;
268
  remove(): void;
269
  firstNode(): Node | undefined;
270
  el?: HTMLElement | Text;
271
  parentEl?: HTMLElement;
272
  isOnlyChild?: boolean;
273
  key?: any;
274
}
275

276
type BDom = VNode<any>;
277
```
278

279
### Validation Types
280

281
```typescript { .api }
282
type Schema = string[] | { [key: string]: TypeDescription };
283
type TypeDescription = BaseType | TypeInfo | ValueType | TypeDescription[];
284
type BaseType = { new (...args: any[]): any } | true | "*";
285

286
interface TypeInfo {
287
  type?: TypeDescription;
288
  optional?: boolean;
289
  validate?: Function;
290
  shape?: Schema;
291
  element?: TypeDescription;
292
  values?: TypeDescription;
293
}
294
```
295

296
### Error Types
297

298
```typescript { .api }
299
class OwlError extends Error {
300
  cause?: any;
301
}
302
```