@thebase/ui
Version:
CDN-installable Owl and Bootstrap 5 UI component library.
239 lines (174 loc) • 13.8 kB
Markdown
# Usage Guide — Integrating BaseUI Into a Project
This is the single entry point for adding BaseUI to a consumer project (a static page, a Base HUB website page, a server-rendered app, or your own Owl app). It sequences the existing reference docs into one path and gives copy-paste-ready examples — read the linked page for exhaustive detail on any step.
Audience: engineers and AI coding agents integrating `@thebase/ui` into a project that is **not** this repository.
## Quick start (copy-paste, works as-is)
Save this as an `.html` file and open it — no build step, no server required. It installs BaseUI from the pinned CDN and renders a button, an input, and a card using the static `b-ui` markup API (the zero-build alternative). If you're building an Owl app, skip straight to the [pure Owl install](#2-install-pure-owl-api--recommended) below — it's the recommended way to consume BaseUI.
```html
<html lang="en">
<head>
<meta charset="utf-8">
<title>BaseUI quick start</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
</head>
<body>
<div b-ui="card" style="max-width: 24rem; margin: 2rem auto;">
<div b-card-header>Sign in</div>
<div b-card-body>
<input b-ui="input" type="email" placeholder="name@example.com">
</div>
<div b-card-footer>
<button b-ui="button" b-att-variant="default" type="button">Continue</button>
</div>
</div>
</body>
</html>
```
`https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/...` is the real jsDelivr URL for the published `@thebase/ui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@0.0.4`) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
The static bundle calls `BaseUI.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `BaseUI.mountAll(root)` yourself only after injecting new markup or when mounting a specific fragment. If the consumer is itself an Owl app, use [step 2](#2-install-pure-owl-api--recommended) instead — that's the recommended path.
## 1. Decide which API you need
| You are building... | Use | Install | Full reference |
| --- | --- | --- | --- |
| Your own Owl app that wants `<Button/>`, `<Card/>`, `<Dialog/>` as real component classes | The pure Owl component API (recommended) | CSS + the same `baseui.min.js`/`baseui.esm.js` (via `@base/owl`/`@base/component` import-map keys or a plain npm import) + `dist/baseui.templates.xml` | [Pure Owl Components](owl-components.md) |
| Static HTML, a server-rendered page, or a Base HUB website page with no Owl runtime | The static `b-ui` markup API (alternative) | One CSS file + one `<script>` tag | [Installation](installation.md) |
Both APIs come from the same package and the same CSS file, and can be mixed on one page. Prefer the pure Owl component API by default — real component classes, props, and slots compose more predictably than markup attributes. Reach for the static API only when the target page has no Owl runtime of its own (plain HTML, server-rendered templates, a Base HUB website page) and adding one isn't worthwhile just to use BaseUI.
**[VERIFY]** Before choosing, confirm whether the target project already runs Owl (check for `@odoo/owl` or `@base/owl` in its `package.json`), or whether it's a plain page you'd rather not add a component-mount step to. Use the static API for the latter.
## 2. Install (pure Owl API — recommended)
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
<script type="importmap">
{
"imports": {
"@base/owl": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
"@base/component": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
"@base/theme": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
"@base/templates": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.templates.xml"
}
}
</script>
```
`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@0.0.4`) instead of `@latest` for production.
```html
<script type="module">
import { Component, mount, xml } from "@base/owl";
import { Button, Card, CardBody, CardHeader, CardTitle } from "@base/component";
const templates = await fetch(import.meta.resolve("@base/templates")).then((r) => r.text());
class Root extends Component {
static components = { Button, Card, CardBody, CardHeader, CardTitle };
static template = xml`
<Card>
<CardHeader><CardTitle>Hello</CardTitle></CardHeader>
<CardBody>
<Button variant="'default'" label="'Save'" onClick="() => console.log('saved')"/>
</CardBody>
</Card>`;
}
await mount(Root, document.getElementById("app"), { templates });
</script>
```
`@base/owl`, `@base/component`, and `@base/theme` all resolve to the exact same `dist/baseui.esm.js` — the one file this whole guide installs for the static API too. For npm/bundler usage, skip the import map entirely and import everything straight from `@thebase/ui` (plus `@thebase/ui/dist/baseui.templates.xml` as a fetch target) — see [Pure Owl Components](owl-components.md#npm--bundler-usage).
Two rules that account for most integration failures — see [Pure Owl Components](owl-components.md#common-mistakes) for the worked example:
1. `dist/baseui.templates.xml` must be loaded and passed to `mount()` before any BaseUI tag renders.
2. Import Owl itself from `@base/owl`, never `@odoo/owl` — otherwise the consumer's `Component` class and BaseUI's are different runtime identities and mounting throws.
## 3. Install (static `b-ui` API — alternative, no Owl runtime needed)
**Option A — CDN (static HTML, no build step):**
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
```
`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@0.0.4`) instead of `@latest` for production.
**Option B — npm (bundler-based apps: Vite, webpack, etc.):**
```sh
npm install @thebase/ui
```
```js
import "@thebase/ui/baseui.css";
import "@thebase/ui"; // side-effect import: registers window.BaseUI and auto-mounts on DOMContentLoaded
```
`dist/baseui.min.js`/`baseui.esm.js` are fully self-contained — Bootstrap's JS bundle and the Owl runtime are embedded ahead of BaseUI's own code, in load order, inside this one file. No other script or import is needed for the static API.
Rule that applies to both options:
- Production pages must use a pinned version (e.g. `@thebase/ui@0.0.4`), never `@latest`.
Mount markup:
```html
<button b-ui="button" b-att-variant="default" type="button">Save</button>
```
Initial page markup mounts automatically. `BaseUI.mountAll()` scans for `[b-ui]` and `[b-icon]` and is idempotent — call it again after injecting new markup (e.g. after an AJAX partial render). Runtime API surface: [Runtime API](runtime-api.md).
### Quick component snippets
Copy-paste starting points for the components you'll reach for first. Every component's full attribute/event/accessibility reference lives under [`docs/components/`](components/) — look up the specific component before shipping.
```html
<!-- Button -->
<button b-ui="button" b-att-variant="default">Save</button>
<button b-ui="button" b-att-variant="outline" b-att-size="sm">Cancel</button>
<!-- Input -->
<input b-ui="input" type="email" placeholder="name@example.com">
<!-- Card -->
<div b-ui="card">
<div b-card-header>Title</div>
<div b-card-body>Content</div>
<div b-card-footer>Footer</div>
</div>
<!-- Dialog -->
<button b-att-trigger="#settings-dialog">Open</button>
<div b-ui="dialog" b-att-trigger="[b-att-trigger='#settings-dialog']" id="settings-dialog">
<div b-dialog-panel>
<h2>Settings</h2>
<button b-dialog-close>Close</button>
</div>
</div>
<!-- Icon -->
<span b-icon="search"></span>
```
## 4. Theme the install
```html
<html b-theme="dark">
```
```js
BaseUI.theme.set("dark");
BaseUI.theme.set({ primary: "#0057d8", radius: "0.5rem" });
```
For a persisted toggle like the docs/examples use:
```html
<button b-ui="theme-button" b-att-variant="outline" type="button"></button>
```
Or control the same theme state from JavaScript:
```js
import { createThemeController } from "@base/theme";
const theme = createThemeController();
theme.init();
```
Full token list and the shadcn-aligned default palette: [Theming](theming.md).
## 5. Add icons (optional, no extra install)
```html
<button b-ui="button" b-att-variant="outline" type="button" aria-label="Open sidebar">
<span b-icon="panel-left" b-icon-size="1rem"></span>
</button>
```
Icons ship with the normal BaseUI assets — no separate script tag, and every Lucide icon name is available by kebab-case (`panel-left`), camelCase, or snake_case. Sizing, color, accessibility rules, and self-hosting: [Built-in Icons](icons.md).
## 6. Copy a block instead of assembling from primitives
For common layouts (dashboard shells, sidebars, login/signup forms, charts), copy a ready-made block from the gallery instead of composing primitives by hand: [Blocks](blocks.md).
## 7. Verify the integration
- [ ] Only `baseui.min.css` + `baseui.min.js` (or `baseui.esm.js`) are loaded — no separate `baseui.owl.*`/`bootstrap.bundle.min.js`/`baseui.components.esm.js` files needed, for either API.
- [ ] `BaseUI.version` returns the expected pinned version in the browser console.
- [ ] Initial static markup mounts without an extra call; injected markup mounts after `BaseUI.mountAll(root)`.
- [ ] Pure Owl components render with no console errors (a missing-template error means step 2's `dist/baseui.templates.xml` load is missing or unawaited).
- [ ] Toggling `b-theme` actually changes rendered colors (a no-op usually means CSS custom properties are being overridden by the consumer's own stylesheet loaded after `baseui.min.css`).
- [ ] Look up the specific component in [`docs/components/`](components/) for its attributes, events, and accessibility notes before wiring it up.
## 8. Troubleshooting
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `ReferenceError: BaseUI is not defined` | The bundle script hasn't run yet, or its `<script>` tag is missing/mistyped. | Confirm the `<script src=".../baseui.min.js" defer>` tag is present and the network tab shows it loading (200, not 404). |
| Components render unstyled (plain HTML, no Bootstrap look) | `baseui.min.css` isn't loaded, or loaded after your own stylesheet overrides it. | Load `baseui.min.css` in `<head>`, before any of your own CSS that touches the same elements. |
| `tabs` (or another Owl-backed static component) silently does nothing | `baseui.min.js` didn't finish loading. | Confirm `baseui.min.js` loads (network tab, 200 not 404). |
| Pure Owl mount throws `"X is not a Component. It must inherit from the Component class"` | Your app imports `@odoo/owl` directly somewhere instead of `@base/owl`. | Replace every `@odoo/owl` import with `@base/owl` in your own app code — both must resolve to the same `globalThis.owl` instance. |
| Pure Owl component renders blank / throws a template-not-found error | `dist/baseui.templates.xml` was never fetched and passed to `mount()`. | Fetch the templates string and pass it as `{ templates }` to `mount()` (or `app.addTemplates(...)`) before rendering any BaseUI tag. |
| New markup injected via AJAX/fetch doesn't turn into components | Auto-mount only covers markup present when the bundle initializes. | Call `BaseUI.mountAll(root)` after injecting new `[b-ui]` or `[b-icon]` markup — it's idempotent, safe to call repeatedly. |
| `BaseUI.theme.set(...)` has no visible effect | A page stylesheet loaded after `baseui.min.css` re-hardcodes the same properties, or the element isn't a descendant of the themed root. | Load consumer CSS after BaseUI's, and confirm `b-theme` is set on `<html>` or an ancestor of the components you expect to change. |
## 9. Common mistakes
- Adding a `baseui.owl.min.js`/`bootstrap.bundle.min.js`/`baseui.components.esm.js` script tag "just in case" — none of those files are published anymore; `baseui.min.js`/`baseui.esm.js` embed everything.
- Using `/latest/` CDN paths in production instead of a pinned version.
- Assuming auto-mount watches the DOM forever — it does not; call `BaseUI.mountAll(root)` after injecting new `[b-ui]` markup client-side (e.g. from a fetched partial).
- Mixing `@odoo/owl` imports into a project that also imports `@thebase/ui` — always go through `@base/owl`.
- Expecting `BaseUI.mountAll()` to pick up Owl component tags (`<Button/>`) — it only mounts static `[b-ui]` markers; pure Owl components are registered and mounted through your own app's `static components` + `mount()`, per step 2.
## Related docs
[Installation](installation.md) · [Runtime API](runtime-api.md) · [Theming](theming.md) · [Built-in Icons](icons.md) · [Pure Owl Components](owl-components.md) · [Blocks](blocks.md) · [Component Authoring](component-authoring.md) (for contributing to BaseUI itself, not for consuming it) · [Registry](registry.md) · [Component Reference index](components/button.md) (per-component pages live under `docs/components/`)