The Base UI

The Base UI is a CDN-installable UI kit built with Bootstrap 5 styling and Owl-enhanced behavior. The primary way to consume it is as pure Owl components (<Button/>-style imports into your own Owl app); the static b-ui markup adapter is the alternative for plain static HTML, server-rendered pages, and Base HUB website pages that have no Owl app of their own.

Its strong points: no build step — every component runs straight from a CDN <script>/import map, nothing to compile; modular component design — each component is a self-contained unit you import or mark up individually, not a monolith; vanilla JavaScript/TypeScript — no framework lock-in, no JSX, no compiler-specific syntax to learn; and this combination makes it well suited to building WYSIWYG website builders, where components must mount, unmount, and re-render dynamically from user-driven markup or drag-and-drop edits rather than a fixed build-time component tree.

Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the @latest tag for readability; pin an exact version instead (e.g. @0.0.11) for any production page, since @latest can change what your page loads the moment a new version ships. Pure Owl usage:

<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>
<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>

unpkg mirrors the same files as an alternative CDN — swap any cdn.jsdelivr.net/npm URL above for unpkg.com (e.g. https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js) if jsDelivr is unreachable in your environment. See Pure Owl Components for the full API, npm/bundler usage, and mixing with the static adapter.

If you have no Owl app, use the static b-ui markup adapter instead — one stylesheet and one script tag, no import map:

<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>

dist/baseui.min.js/baseui.esm.js are fully self-contained and back both APIs above: Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper are all embedded in load order (Bootstrap, then Owl, then BaseUI) — one file, nothing else to load first. There is no separate baseui.owl.*/baseui.components.esm.js/baseui.theme.esm.js. (dist/bootstrap.bundle.min.js still ships standalone, unmodified, for a project that wants vendored Bootstrap JS on its own — BaseUI itself never needs it loaded separately.)

BaseUI exposes every component (73 in the current registry) as a real Owl component class — see Pure Owl Components for the complete API, npm/bundler usage, and mixing with the static adapter.

For app-level theme controls, import createThemeController/BaseUITheme as @base/theme in browser import maps (pointing at the same dist/baseui.esm.js) or straight from @thebase/ui in npm/bundler apps, to create persisted light/dark toggles like the documentation pages use.

Every component ships both APIs from src/components/<name>/: the static b-ui adapter (<name>.js, using b-att-* attributes and baseui:* events) and a pure Owl component class (<name>.component.js, exported from @thebase/ui/components). A few components' pure Owl treatment is intentionally lighter or reshaped versus their static markup-driven adapter — most notably chart (a slotted container; static Chart.js bootstrapping stays a b-ui-only concern) and the data-driven data-table/combobox/command/calendar (props-driven instead of slot/markup-driven). See each component's doc page under docs/components/ for specifics.

Release notes

See CHANGELOG.md for the full version history. Current published version: 0.0.11.

Project Documents

Use these documents as the canonical project map:

• Usage Guide is the single entry point for integrating BaseUI into a consumer project — start here, then follow its links into the reference docs below.
• Installation covers CDN, npm, self-hosted usage, icon assets, pinned versions, and release guardrails.
• Runtime API documents the window.BaseUI global, mounting lifecycle, theming API, and destroy behavior.
• Registry explains dist/baseui.registry.json, build files, block metadata, component metadata, and integrity hashes.
• Theming describes b-theme, runtime theme overrides, shadcn-aligned tokens, Bootstrap variable mapping, and shared example theme persistence.
• Built-in Icons covers the Lucide icon library, b-icon markup, accessibility rules, self-hosted icon paths, and JavaScript helpers.
• Component Authoring defines the src/components/<name>/ source contract, component registration rules, event naming, cleanup requirements, and CSS scoping policy. Repo-only — not published to npm (see below).
• Pure Owl Components covers the pure Owl component API (@thebase/ui + dist/baseui.templates.xml), what to load, and common mistakes.
• Blocks documents copyable static shadcn-style blocks, source stylesheet ownership under examples/blocks/, gallery/viewer URLs, and block icon rules.
• Component Reference starts the per-component documentation set in docs/components/; each component page includes usage, attributes, events, accessibility notes, and test guidance where relevant.
• Frontend Implementation Plan records the completed BaseUI 1.0.0 delivery checklist and earlier decisions for engineering context.
• Historical Product Plan preserves the original Bootstrap 5 + Owl product brief; use current docs/ and registry files when they disagree with older planning assumptions.

The links above work as-is when browsing this repo. docs/*.md and docs/components/ also ship inside the published npm package (see files in package.json), so the same docs are reachable straight from a CDN without cloning the repo — no HTML rendering, just the raw Markdown source:

https://unpkg.com/@thebase/ui@latest/docs/usage-guide.md
https://unpkg.com/@thebase/ui@latest/docs/components/button.md
https://cdn.jsdelivr.net/npm/@thebase/ui@latest/docs/usage-guide.md

Drop the version (@thebase/ui/docs/...) to always resolve to latest, or pin a version the way the rest of this README recommends pinning dist/ assets. docs/v2/ (the vendored general Owl framework reference) and docs/component-authoring.md (BaseUI's own component-authoring contract) are intentionally not published — they're development-time references for working inside this repo, not something a consumer needs to use the library.

Development

npm install
npm run build
npm run dev

Open examples/index.html through the dev server to test the browser build.

examples/index.html is the single Owl app shell for docs, the component gallery, the block gallery, icons, and the chart catalog, all reachable through one main-nav and hash routes (#/docs, #/components, #/blocks, #/icons, #/chart). Old bookmarked URLs like /docs and /blocks redirect to their hash-route equivalent. Each block has a shadcn-style Preview/Code/responsive viewer plus its source stylesheet colocated in examples/blocks/. examples/charts/index.html mirrors the current shadcn chart catalog with interactive BaseUI examples for area, bar, line, pie, radar, radial, and tooltip charts, and is embedded inline at #/chart.

BaseUI includes the full Lucide SVG icon set as a built-in icon library. Use <span b-icon="search"></span> in HTML, or BaseUI.icons.lucide.url("search") from JavaScript. Builds publish all SVGs to dist/icons/lucide/ and an index at dist/icons/lucide.json.

Package Scripts

• npm run dev starts a static server for examples and built dist/ assets.
• npm run build creates CDN and npm artifacts in dist/.
• npm run lint checks JavaScript and CSS policy.
• npm run test runs runtime tests.
• npm publish runs prepublishOnly first.

Distribution

The npm package publishes the built dist/ artifacts plus package metadata. The browser build bundles Bootstrap CSS, and dist/baseui.min.js/baseui.esm.js embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's .behavior.js/runtime/*.js helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. dist/bootstrap.bundle.min.js also ships standalone (unmodified) and dist/baseui.icons.esm.js stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.

The published tarball also carries docs/*.md and docs/components/ (see the "Project Documents" section above), README.md, CHANGELOG.md, and LICENSE — docs/v2/ and docs/component-authoring.md are deliberately excluded from package.json's files list since they're development-time-only references for working inside this repo.