Oatbase Extensions for Oat UI

Advanced components for Oat UI.

Keep Oat’s semantic HTML, tiny footprint, and token system. Add Oatbase when a product needs richer selection, navigation, content, or application patterns. The complete Oat-inclusive CSS and JavaScript stays under 30 kB gzipped; the extension-only layer stays under 20 kB. Individual entries let applications pay only for the pieces they use.

Browse additions Install Oatbase

Local package

Use the source checkout today.

Oatbase is not published yet. Install the local folder to use its complete Oat-inclusive bundle in another project.

npm install ../oatbase

Oat core patterns: 34
Oatbase additions: 35
Documented patterns: 69

Choose the smallest useful layer

Oat remains the foundation. Oatbase fills deliberate gaps without replacing Oat’s components or creating another theme contract.

O

Start with Oat core

Buttons, fields, dialogs, tables, tabs, alerts, and other common interface primitives.

+

Add Oatbase where needed

Richer selection, navigation, content, and product-oriented compositions.

Useful starting points

A short cross-section of the extension layer. Use the navigation or search to reach the complete catalog.

⌕

Combobox

Searchable selection backed by a native select.

⌘

Command

Fast filtering and keyboard access.

⌘

Tree

Hierarchical navigation with native disclosure.

▣

Lightbox

An image viewer composed from Oat primitives.

¹

Footnotes

Readable previews without hiding source notes.

↧

Reading progress

A native progress element tied to long content.

Reference

Components

Browse Oatbase additions and the Oat core patterns available through the complete bundle. The source filter makes the ownership boundary explicit.

Browse by source

Compositions

Recipes

Application patterns composed from Oat and Oatbase components. Recipes show ownership boundaries without growing the component bundle.

Data management

Filter toolbar

Compose an Oat field, Toolbar, and Data Table. Filtering coordinates rows already in the document.

HTML

<ot-data-table>
  <div data-table-toolbar>
    <label data-field>Filter
      <input type="search" data-table-filter>
    </label>
    <ot-toolbar role="toolbar" aria-label="Table actions">
      <button type="button">Add project</button>
    </ot-toolbar>
  </div>
  <table>…</table>
</ot-data-table>

Bulk selection

Reveal application-owned actions from Data Table’s oatbase:select event. Destructive confirmation remains native application behavior.

HTML and JavaScript

<ot-data-table id="projects">
  <div data-bulk-actions hidden>
    <button type="button">Archive selected</button>
  </div>
  <table>…</table>
</ot-data-table>

<script>
  const projects = document.querySelector('#projects');
  projects.addEventListener('oatbase:select', event => {
    projects.querySelector('[data-bulk-actions]').hidden =
      event.detail.values.length === 0;
  });
</script>

Row actions

Place an Oat dropdown in a native table cell without turning the entire row into a button.

HTML

<tr>
  <th scope="row">Atlas</th>
  <td>Active</td>
  <td>
    <ot-dropdown>
      <button popovertarget="atlas-actions" aria-label="Actions for Atlas">⋯</button>
      <menu id="atlas-actions" popover>
        <button role="menuitem">Open</button>
        <button role="menuitem">Archive</button>
      </menu>
    </ot-dropdown>
  </td>
</tr>

Filtered empty state

Pair data-table-empty with the compact Empty variant. The table component owns visibility; the application owns recovery actions.

HTML

<ot-data-table>
  <input type="search" data-table-filter aria-label="Filter projects">
  <table>…</table>
  <section data-variant="empty" data-size="compact" data-table-empty hidden>
    <h3>No projects found</h3>
    <p>Try another filter.</p>
  </section>
</ot-data-table>

Content and files

Attachment row

Combine Item media, metadata, actions, and Oat Upload. Upload transport remains application code.

HTML

<article class="item" data-variant="outline">
  <span data-slot="media" aria-hidden="true">PDF</span>
  <section><h3>Report.pdf</h3><p>2.4 MB</p></section>
  <span data-slot="actions">
    <button type="button" class="ghost">Remove</button>
  </span>
</article>

Code and copy

Compose native preformatted source with Copy Button. Oatbase copies text; syntax rendering remains optional.

HTML

<ot-copy>
  <pre data-copy-source><code>npm install @oddship/oatbase</code></pre>
  <button type="button" class="outline" data-copy-button>Copy</button>
</ot-copy>

Workflow applications

Key/value editor

Compose Repeater with native fields. Parsing and domain validation remain application logic.

HTML

<ot-repeater data-min="1">
  <div data-repeater-list>…</div>
  <button type="button" data-repeater-add>Add variable</button>
  <template data-repeater-template>
    <fieldset data-repeater-item>…</fieldset>
  </template>
</ot-repeater>

Validation summary

Link an Oat alert or Callout to invalid native fields instead of creating parallel error state.

HTML

<aside role="alert" aria-labelledby="validation-title">
  <strong id="validation-title">Fix two fields</strong>
  <ul>
    <li><a href="#email">Enter a valid email address</a></li>
    <li><a href="#timezone">Choose a timezone</a></li>
  </ul>
</aside>

Page header

Combine semantic headings, an Oat Badge, and Toolbar actions in a responsive stack.

HTML

<header class="hstack justify-between">
  <div><span class="badge">Draft</span><h1>Release notes</h1></div>
  <ot-toolbar role="toolbar" aria-label="Page actions">
    <button type="button" class="outline">Preview</button>
    <button type="button">Publish</button>
  </ot-toolbar>
</header>

Searchable action rail

Filter Item rows beside a Splitter-managed work surface. Selection state remains in the application.

HTML

<ot-splitter>
  <aside>
    <label data-field>Filter<input type="search"></label>
    <nav class="item-group" aria-label="Actions">…</nav>
  </aside>
  <button type="button" data-splitter aria-label="Resize action rail"></button>
  <main>…</main>
</ot-splitter>

Schedule form

Use native date/time controls and Oat fields. Cron parsing, timezone conversion, and persistence stay in application code.

HTML

<fieldset>
  <legend>Schedule</legend>
  <label data-field>Date<input type="date" name="date" required></label>
  <label data-field>Time<input type="time" name="time" required></label>
  <label data-field>Timezone
    <select name="timezone"><option>Asia/Kolkata</option></select>
  </label>
</fieldset>

Blocks

Isolated full examples

Complete pages assembled from shipped Oat and Oatbase primitives. Each preview runs in an opaque-origin sandbox with no access to the documentation page; switch to Code for the full document.

Local paths: these runnable documents load the current checkout’s dist/ files. Package imports remain documented on each component page.

Getting started

Installation

Oatbase has not been published to a package registry or CDN yet. Use the current source checkout locally while the first release is prepared.

Local package

Release status: Oatbase has not been pushed to npm or a CDN. It will publish as @oddship/oatbase; the commands below use your local source checkout before that first release.

Enter nix develop to use the checked-in development shell, or install Bun, Node.js/npm, and GNU Make. Then install dependencies and build the distribution from the Oatbase directory:

npm ci
make dist

Then install that directory from your application. Adjust the relative path to match your checkout:

npm install ../oatbase

import '@oddship/oatbase/css';
import '@oddship/oatbase';

Static files

After building, copy dist/ into your site and reference the complete bundle. Oat’s CSS and JavaScript are already included.

cp -R ../oatbase/dist ./public/vendor/oatbase

<link rel="stylesheet" href="/vendor/oatbase/oatbase.min.css">

<script src="/vendor/oatbase/oatbase.min.js" defer></script>

Individual imports

Projects that already load Oat can add only the extensions they use. The extension-only aggregate is also available as @oddship/oatbase/extensions.css and @oddship/oatbase/extensions.

import '@knadh/oat/oat.min.css';
import '@knadh/oat/oat.min.js';

import '@oddship/oatbase/combobox.css';
import '@oddship/oatbase/combobox';

// CSS-only additions need no JavaScript import.
import '@oddship/oatbase/drawer.css';
import '@oddship/oatbase/item.css';

Getting started

Principles

Oatbase extends Oat without creating a second component system on top of it.

Native first

If an Oat or native HTML element solves the problem, use it. The drawer is CSS around <dialog>; the combobox keeps a real <select> as its form control and fallback.

Progressive enhancement

Forms still submit and essential controls remain usable before JavaScript loads. JavaScript adds search, keyboard movement, and richer interaction rather than basic access.

Small pieces

Every component is independently loadable. The aggregate bundle is a convenience, not a requirement.

Oat tokens

Oatbase introduces no parallel theme. It consumes variables such as --card, --border, --accent, Oat’s spacing scale, and its --radius-* scale. The documentation intentionally preserves those radius defaults.

Getting started

Customizing

Oat owns the visual language. Oatbase inherits it and exposes only the component geometry that Oat cannot describe.

Theme contract

Override Oat’s semantic variables after the default Oatbase stylesheet. With extension-only imports, place the overrides after Oat and before or after the extensions. The same palette, type, spacing, radius, shadow, and motion values flow through both layers.

:root {
  --primary: light-dark(#315c45, #9bd4b4);
  --primary-foreground: light-dark(#fff, #102117);
  --background: light-dark(#faf8f2, #10110f);
  --card: light-dark(#fff, #181a17);
  --radius-medium: 0.25rem;
}

Included themes

Oatbase ships four alternative token maps plus an explicit Oat reset for nested scopes. The top-bar theme picker provides five choices. Presets contain no component selectors or JavaScript.

Theme	Character
Oat	The unchanged Oat foundation.
Doordarshan	Monospace, terracotta, saffron, peacock, and warm terminal surfaces.
Forest	Quiet greens and natural neutral surfaces.
Ocean	Cool blue surfaces with cyan accents.
Paper	Warm editorial surfaces with a serif stack and restrained corners.

/* All presets, including the scoped Oat reset */
import '@oddship/oatbase/themes';

/* Or one independently */
import '@oddship/oatbase/themes/doordarshan.css';

document.documentElement.dataset.oatTheme = 'doordarshan';

Scoped theme lab

The preset select and native radio controls apply the shipped variables only to the preview. The rest of the documentation keeps its top-bar selection.

Component geometry hooks

Oatbase variables are prefixed and have local fallbacks. Override them globally, within a subtree, or on one component.

Hook	Purpose
--oatbase-overlay-background	Shared command and drawer backdrop.
--oatbase-drawer-size	Inline size of left and right drawers.
--oatbase-drawer-max-height	Top and bottom drawer height limit.
--oatbase-drawer-motion-offset	Drawer entrance and exit distance.
--oatbase-command-width	Command dialog width.
--oatbase-command-max-height	Command dialog height limit.
--oatbase-command-list-max-height	Command results height limit.
--oatbase-listbox-max-height	Shared popup limit for selection controls.
--oatbase-otp-cell-size	OTP presentation cell size.
--oatbase-otp-gap	Gap between OTP presentation cells.
--oatbase-chart-height	Minimum chart plotting height.
--oatbase-chart-grid-size	Chart grid interval.
--oatbase-splitter-min-height	Minimum splitter block size.
--oatbase-splitter-handle-size	Splitter handle hit area.
--oatbase-splitter-grip-size	Splitter grip length.
--oatbase-empty-min-height	Minimum empty-state block size.
--oatbase-empty-compact-min-height	Compact empty-state minimum height.
--oatbase-empty-content-width	Empty-state content width limit.
--oatbase-scrollbar-size	Scroll Area scrollbar thickness.
--oatbase-toolbar-offset	Sticky toolbar offset.
--oatbase-stepper-marker-size	Stepper marker size.
--oatbase-stepper-track-size	Stepper progress-track thickness.
--oatbase-timeline-marker-size	Timeline marker size.
--oatbase-rating-size	Rating symbol size.
--oatbase-stat-value-size	Prominent statistic value size.
--oatbase-action-field-value-size	Action Field value size.
--oatbase-lightbox-width	Lightbox dialog width.
--oatbase-lightbox-image-height	Lightbox image height limit.
--oatbase-footnote-width	Footnote preview width.
--oatbase-footnote-max-height	Footnote preview height limit.
--oatbase-prose-width	Prose measure.
--oatbase-log-min-height	Log output minimum height.
--oatbase-log-max-height	Log output maximum height.

.verification-code {
  --oatbase-otp-cell-size: 2.75rem;
  --oatbase-otp-gap: var(--space-1);
}

Appearance mode

<ot-theme-switcher> selects system, light, or dark appearance by setting color-scheme. Explicit light and dark choices also set data-theme on the document root so scoped Oat overrides work as documented.

Component · JavaScript

Command

A command palette with local or application-supplied results, keyboard navigation, and an optional global shortcut.

Preview

<ot-command data-shortcut="mod+k">
  <button data-command-open commandfor="commands" command="show-modal">Open</button>
  <dialog id="commands" closedby="any">
    <input data-command-search type="search" placeholder="Type a command…">
    <ul data-command-list>
      <li data-command-group>Navigation</li>
      <li><button data-command-item data-value="home">Go home</button></li>
      <li data-command-empty hidden>No commands found.</li>
    </ul>
  </dialog>
</ot-command>

import '@oddship/oatbase/command';

const command = document.querySelector('ot-command');
command.addEventListener('oatbase:select', event => {
  console.log(event.detail.value);
});

Usage

import '@oddship/oatbase/command.css';
import '@oddship/oatbase/command';

Handling selection

command.addEventListener('oatbase:select', (event) => {
  console.log(event.detail.value);
});

Call event.preventDefault() to keep the palette open after selection.

Application-supplied results

Set data-filter="manual" when results come from an API or application index. Oatbase emits each query without hiding existing rows. Replace or update the semantic list, then call refresh() so keyboard focus, aria-activedescendant, groups, and the empty state reflect the new DOM.

<ot-command id="project-command" data-filter="manual">
  <button data-command-open>Search projects</button>
  <dialog aria-label="Project search">
    <input data-command-search type="search" aria-label="Search projects">
    <ul data-command-list aria-busy="false">
      <li data-command-empty hidden>No projects found.</li>
    </ul>
  </dialog>
</ot-command>

<script type="module">
  const command = document.querySelector('#project-command');
  let request = 0;

  command.addEventListener('oatbase:query', async event => {
    const current = ++request;
    command.list.setAttribute('aria-busy', 'true');
    const projects = await searchProjects(event.detail.query);
    if (current !== request) return;

    const empty = command.querySelector('[data-command-empty]');
    command.list.replaceChildren(...projects.map(projectRow), empty);
    command.list.setAttribute('aria-busy', 'false');
    command.refresh();
  });
</script>

The application owns fetching, cancellation, caching, and result markup. Each selectable result still uses data-command-item. A listener may also cancel oatbase:query to suppress local filtering for one query.

Global shortcut

Add data-shortcut="mod+k" to open with Command-K on macOS or Control-K elsewhere.

API

Surface	Purpose
`data-shortcut="mod+k"`	Registers the optional global Command-K or Control-K shortcut.
`data-command-open / data-command-close`	Opt existing buttons into opening or closing the palette.
`data-command-search / data-command-list`	Identify the search input and semantic result list.
`data-command-item`	Marks a selectable result. Use `aria-disabled="true"` for an unavailable result.
`data-value / data-keywords`	Provide the emitted value and additional searchable text.
`data-filter="manual"`	Leaves filtering and result insertion to the application; Oatbase continues to own listbox navigation and selection.
`data-keep-open`	Keeps the dialog open after that item is accepted.
`query`	Returns the current trimmed query string.
`items / visibleItems`	Expose all result elements or the currently available filtered results.
`open() / close()`	Control the native dialog programmatically.
`refresh()`	Reindexes inserted results and synchronizes roles, active item, groups, empty state, and `aria-activedescendant`.
`oatbase:query`	Cancelable event with `{ query }`. Canceling it skips local filtering for that input.
`oatbase:select`	Cancelable event with `{ value, item }`; preventing default keeps the palette open.
`oatbase:open / oatbase:close`	Report palette lifecycle changes.

Component · CSS only

Drawer

A native dialog styled as a sheet from the top, right, bottom, or left edge.

Preview

<button commandfor="settings" command="show-modal">Open drawer</button>
<dialog id="settings" data-variant="drawer" data-side="right" closedby="any">
  <form method="dialog">
    <header><h3>Settings</h3></header>
    <div data-drawer-body>Drawer content</div>
    <footer><button value="done">Done</button></footer>
  </form>
</dialog>

Usage

import '@oddship/oatbase/drawer.css';

No Oatbase JavaScript is involved. Oat’s commandfor compatibility layer and native dialog behavior handle interaction.

Sides

Set data-side to top, right, bottom, or left.

Component · CSS only

Item

Composable rows for navigation, settings, results, and compact content lists.

Preview

Connected navigation

◫
Design system
12 components · Updated Sep 1
Active
⌁
Website refresh
8 components · Updated Aug 31

Outline with actions

◇

Mobile app

3 components · Updated Aug 25

<ul class="item-group" data-connected>
  <li><a class="item" href="/project">…</a></li>
  <li><a class="item" href="/project">…</a></li>
</ul>

<article class="item" data-variant="outline" data-interactive tabindex="0">
  <span data-slot="media">◇</span>
  <section><h3>Mobile app</h3><p>Updated <time datetime="2026-08-25">Aug 25</time></p></section>
  <span data-slot="actions"><button>Archive</button><button>Open</button></span>
</article>

Usage

import '@oddship/oatbase/item.css';

Structure

Use data-slot="media" for a leading icon or avatar and data-slot="actions" for trailing controls. Items can be links, buttons, or articles.

Variants

Add data-variant="outline" to an individual item, or data-connected to an item group for a shared border.

Component · CSS only

Empty

A centered state for collections or views that do not have content yet.

Preview

◇

No projects yet

Create your first project to start organizing work.

<section data-variant="empty">
  <span data-slot="media">◇</span>
  <h3>No projects yet</h3>
  <p>Create your first project to start organizing work.</p>
  <div data-slot="actions">
    <button>Create project</button>
  </div>
</section>

Usage

import '@oddship/oatbase/empty.css';

Guidance

Explain why the view is empty and offer one clear next action. Use semantic headings and paragraphs; the component only supplies layout.

Component · CSS only

Kbd

Compact labels for documenting keyboard shortcuts using the native <kbd> element.

Preview

Open search⌘K

Create projectC

Move between itemsJK

Inside a compact control

<p>Open search <span class="kbd-group"><kbd>⌘</kbd><kbd>K</kbd></span></p>
<p>Create project <kbd>C</kbd></p>
<button class="outline small">Search <kbd data-variant="inline">⌘ K</kbd></button>

Usage

import '@oddship/oatbase/kbd.css';

Use <kbd> for each physical key and wrap combinations in .kbd-group. Set data-variant="inline" when a shortcut is embedded inside another compact control and should not create a nested keycap surface. Keyboard hints are documentation; wire the actual shortcut separately.

Use the source checkout today.

Choose the smallest useful layer

Start with Oat core

Add Oatbase where needed

Useful starting points

Combobox

Command

Tree

Lightbox

Footnotes

Reading progress

Browse by source

No components found

Data management

Content and files

Workflow applications

Local package

Static files

Individual imports

Native first

Progressive enhancement

Small pieces

Oat tokens

Theme contract

Included themes

Scoped theme lab

Component geometry hooks

Appearance mode

Preview

Usage

Handling selection

Application-supplied results

Global shortcut

API

Preview

Usage

Sides

Preview

Design system

Website refresh

Mobile app

Usage

Structure

Variants

Preview

No projects yet

Usage

Guidance

Preview

Usage