What is OWL JS? – The Odoo Web Library Explained

What is OWL JS? – The Simple Definition

OWL stands for Odoo Web Library. It is a component-based JavaScript UI framework created by Odoo — the world's most popular open-source ERP platform used by over 12 million users in 100+ countries. OWL is small (~30 KB gzipped), has zero external dependencies, and is written in TypeScript.

Like React and Vue, OWL lets you build user interfaces by composing reusable components — self-contained pieces of UI that manage their own data and render to the screen. Unlike those frameworks, OWL uses XML templates (inspired by Odoo's long-standing QWeb template engine) rather than JSX or .vue single-file components. If you know HTML, OWL's template syntax will feel immediately familiar.

Your First OWL Component

Here is the simplest possible OWL JS component. A component is an ES6 class that extends Component, and its UI is described by an XML template using the xml tagged template helper:

// OWL JS can be loaded from a CDN or installed via npm (@odoo/owl)
const { Component, mount, xml } = owl;

// 1. Define a component — an ES6 class
class HelloOWL extends Component {

  // 2. Attach an XML template using the xml`` tag helper
  static template = xml`
    <div class="greeting">
      <h1>Hello from OWL JS!</h1>
      <p>I am a component. My name is HelloOWL.</p>
    </div>
  `;
}

// 3. Mount the root component to the real DOM
mount(HelloOWL, document.body);

Three things to notice right away:

1. Class-based — OWL components are ES6 classes that extend Component. If you have done the JavaScript OOP lessons, this syntax is familiar.
2. XML template — The UI is defined as a static template using the xml`` tagged template literal. The template is standard XML enriched with t-* directives.
3. mount() — The mount function takes a component class and a DOM element, renders the component tree, and attaches it to the real DOM.

OWL JS with Reactive State

Static HTML is only the beginning. OWL's real power is its reactivity system. Wrap any object with useState() and OWL will automatically re-render the component whenever that data changes — no manual DOM updates needed.

const { Component, mount, xml, useState } = owl;

class Counter extends Component {
  // useState() wraps an object with a reactive Proxy.
  // Any mutation triggers an automatic re-render.
  state = useState({ count: 0 });

  static template = xml`
    <div class="counter">
      <h2>Count: <t t-esc="state.count"/></h2>
      <button t-on-click="() => state.count++">+ Increment</button>
      <button t-on-click="() => state.count--">- Decrement</button>
      <button t-on-click="() => state.count = 0">Reset</button>
    </div>
  `;
}

mount(Counter, document.body);

What just happened?

• useState({ count: 0 }) creates a reactive Proxy around the object. OWL tracks which component uses which reactive properties.
• t-esc="state.count" — the t-esc directive renders a value into the DOM, HTML-escaped for safety.
• t-on-click="..." — the t-on-* directive attaches a DOM event listener. The part after t-on- is the event name (click, input, change, submit, etc.).
• When state.count is mutated, OWL detects the change and re-renders only the affected parts of the DOM.

OWL JS and Odoo – The Connection

Before Odoo 14, the Odoo web client was built with an older internal framework called Widget (based on Backbone.js). As modern web development evolved, the Odoo team designed OWL from the ground up to replace it. The goals were a cleaner component model, better performance, and first-class developer tooling.

OWL JS Template Directives — A Quick Tour

OWL templates are standard XML enriched with t-* directives for dynamic behaviour. Here is a quick tour of the most important directives you will use daily. Each has its own dedicated lesson later in this course.

<!-- t-esc: render a value (HTML-escaped, safe) -->
<p>Hello, <t t-esc="user.name"/>!</p>

<!-- t-if / t-else: conditional rendering -->
<span t-if="user.isAdmin">Admin</span>
<span t-else="">Guest</span>

<!-- t-foreach / t-as / t-key: loop over a list -->
<ul>
  <li t-foreach="items" t-as="item" t-key="item.id">
    <t t-esc="item.name"/>
  </li>
</ul>

<!-- t-model: two-way binding on form inputs -->
<input t-model="state.query" placeholder="Search..."/>
<p>You typed: <t t-esc="state.query"/></p>

<!-- t-on-*: attach event listeners -->
<button t-on-click="handleSave">Save</button>
<input t-on-input="onInput" t-on-keydown="onKeyDown"/>

<!-- t-att-class: dynamic CSS classes -->
<div t-att-class="{ active: isActive, error: hasError }">...</div>

<!-- Capitalised tag = child component -->
<UserCard name="'Alice'" role="'Admin'"/>

How OWL JS Renders the DOM

OWL uses a virtual DOM strategy. Here is the rendering pipeline step by step:

1. Template compilation — When the app first loads, OWL compiles your XML templates into optimised JavaScript rendering functions. This happens once at startup (or is pre-compiled on the server in production Odoo).
2. Initial render — OWL executes the rendering function with your initial state/props to produce a virtual DOM tree — a plain JavaScript object tree describing the HTML.
3. DOM mounting — OWL converts the virtual DOM tree into actual DOM nodes and inserts them into the real browser DOM.
4. Reactive updates — When state or props change, OWL runs the rendering function again, diffs the new virtual DOM against the previous one, and applies only the minimal DOM changes needed. Unchanged nodes are never touched.

OWL JS vs Vanilla JavaScript

To appreciate what OWL gives you, compare the same interactive counter built with vanilla JavaScript and with OWL JS:

// Vanilla JS — you manage the DOM manually
let count = 0;
const display = document.getElementById('count');

document.getElementById('increment').addEventListener('click', () => {
  count++;
  display.textContent = count;  // Must remember to update DOM every time
});

// For a small counter this is fine.
// For a complex Odoo view with hundreds of fields, events, and conditions,
// manual DOM management becomes unmaintainable very quickly.

// OWL — declare your state and your template; OWL keeps the DOM in sync
class Counter extends Component {
  state = useState({ count: 0 });

  static template = xml`
    <div>
      <p>Count: <t t-esc="state.count"/></p>
      <button t-on-click="() => state.count++">+</button>
    </div>
  `;
  // Zero manual DOM updates — OWL handles everything
}

// As your UI grows, OWL scales cleanly:
// - Split into sub-components
// - Pass data via props
// - Share services via the environment

Key Features of OWL JS at a Glance

OWL JS Versions

There are three major versions of OWL. This course focuses on OWL 2.x, the stable version used in Odoo 16 and 17 — the most widely deployed Odoo versions today.

Using OWL JS Standalone (Without Odoo)

OWL is not locked to the Odoo platform. You can use it as a standalone UI framework for any web project. Install it via npm or load it from a CDN:

# Install via npm
npm install @odoo/owl

<!-- Load OWL from the GitHub release (IIFE build) -->
<script src="https://cdn.jsdelivr.net/npm/@odoo/owl/dist/owl.iife.js"></script>

<!-- owl is now available as a global variable -->
<script>
  const { Component, mount, xml, useState } = owl;
  // ... your app code
</script>