Skip to content

Your First Page ​

Build a real screen — KPI cards, a chart, and a searchable data grid — from an empty file. Roughly 15 minutes.

Every snippet here is markup this build actually ships, lifted from html/_partials/ and html/pages/. Paste one into a page carrying adminvora.css and it is styled.


Step 1 — The document shell ​

html
<!doctype html>
<html lang="en" data-bs-theme="light" data-av-preset="aurora">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Orders · AdminVora</title>

  <script>
    (function () {
      var d = document.documentElement, s;
      try { s = JSON.parse(localStorage.getItem('adminvora.prefs') || '{}'); } catch (e) { s = {}; }

      var mode = s.mode || 'system';
      var dark = mode === 'dark' ||
        (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
      d.setAttribute('data-bs-theme', dark ? 'dark' : 'light');

      ['preset','style','layout','nav-skin','density','radius','sidebar','topbar','width','contrast','motion','depth']
        .forEach(function (k) { if (s[k]) d.setAttribute('data-av-' + k, s[k]); });

      if (s.dir) d.setAttribute('dir', s.dir);

      d.classList.add('av-booting');
      requestAnimationFrame(function () {
        requestAnimationFrame(function () { d.classList.remove('av-booting'); });
      });
    })();
  </script>

  <link rel="icon" href="/adminvora/img/favicon.svg" type="image/svg+xml">
  <link rel="stylesheet" href="/adminvora/css/adminvora.min.css">
</head>
<body>
  <a href="#main" class="av-skip-link">Skip to main content</a>

  <div class="av-shell">
    <!-- sidebar goes here (step 2) -->
    <div class="av-main">
      <!-- topbar goes here (step 3) -->
      <main class="av-content" id="main" tabindex="-1">
        <div class="container-fluid">
          <!-- page content goes here (steps 4–6) -->
        </div>
      </main>

      <footer class="av-footer">
        <span>© 2026 Acme Inc.</span>
        <span>v1.0.0</span>
      </footer>
    </div>
  </div>

  <button class="av-sidebar-backdrop" type="button" data-av-sidebar-backdrop
          aria-label="Close navigation" hidden></button>

  <script src="/adminvora/js/adminvora.js" defer></script>
</body>
</html>

What each part does

ElementPurpose
data-av-* on <html>Theme preference contract — read by CSS, written by the Customizer
Boot scriptApplies stored preferences before first paint; prevents theme flash
.av-skip-linkWCAG 2.4.1 bypass block; visually hidden until focused
.av-shellCSS Grid container defining the sidebar and main regions
.av-contentThe only element that scrolls. The document itself stays one viewport tall
#main with tabindex="-1"Makes the skip-link target programmatically focusable
.av-sidebar-backdropThe dismiss target behind the off-canvas sidebar below 992px

One stylesheet, not two. dist/css/adminvora.min.css already contains tokens.css. The split pair under src/css/ exists so you can regenerate tokens against a custom palette; a consumer links the single file.

Never defer or externalise the boot script. Both reintroduce exactly the flash of the wrong theme it prevents. It is the first script in <head> and it is synchronous on purpose.


Step 2 — Sidebar ​

html
<aside class="av-sidebar" id="avSidebar">
  <div class="av-sidebar__brand">
    <a href="/" class="av-brand">
      <img class="av-brand__mark" src="/adminvora/img/logo-mark.svg" alt="" width="32" height="32">
      <span class="av-brand__text">Acme</span>
    </a>
    <button class="av-btn av-btn--ghost av-btn--icon av-sidebar-collapse" style="--av-btn-height: 30px"
            type="button" data-av-sidebar-toggle
            aria-label="Collapse sidebar" aria-expanded="true" aria-controls="avSidebar">
      <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M15 6l-6 6 6 6"/></svg>
    </button>
  </div>

  <nav class="av-sidebar__nav" aria-label="Main">
    <ul class="av-menu">

      <li class="av-menu__group">
        <details class="av-menu__disclosure" open>
          <summary class="av-menu__title" id="avGroupShop">
            <span class="av-menu__title-text">Shop</span>
            <svg class="av-icon av-menu__caret" aria-hidden="true" viewBox="0 0 24 24"><path d="m6 9 6 6 6-6"/></svg>
          </summary>
          <ul class="av-menu__group-list" aria-labelledby="avGroupShop">

            <li class="av-menu__item">
              <a class="av-menu__link" href="/dashboard">
                <svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
                  <rect x="3" y="3" width="7.5" height="7.5" rx="1.5"/>
                  <rect x="13.5" y="3" width="7.5" height="7.5" rx="1.5"/>
                  <rect x="3" y="13.5" width="7.5" height="7.5" rx="1.5"/>
                  <rect x="13.5" y="13.5" width="7.5" height="7.5" rx="1.5"/>
                </svg>
                <span class="av-menu__label">Dashboard</span>
              </a>
            </li>

            <li class="av-menu__item av-menu__item--active">
              <a class="av-menu__link" href="/orders" aria-current="page">
                <svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
                  <path d="M6 7h12l-1.2 13H7.2L6 7z"/><path d="M9 10V7a3 3 0 0 1 6 0v3"/>
                </svg>
                <span class="av-menu__label">Orders</span>
              </a>
            </li>

          </ul>
        </details>
      </li>

    </ul>
  </nav>
</aside>

Sections are <details>/<summary>, not a JavaScript disclosure. A menu that needs a working bundle in order to open is the wrong trade in the one region that has to survive the bundle failing — the same reasoning that keeps the error pages off the app bundle entirely. Mark the group holding the current page open, and the rail arrives in the right state with no script at all.

The active row needs both halves: av-menu__item--active paints it, aria-current="page" announces it. Neither implies the other, and shipping one without the other is the most common accessibility defect in an admin sidebar.


Step 3 — Topbar ​

html
<header class="av-topbar">
  <div class="av-topbar__start">
    <button class="av-btn av-btn--ghost av-btn--icon av-topbar__menu-btn" type="button"
            data-av-sidebar-toggle aria-label="Open navigation"
            aria-controls="avSidebar" aria-expanded="false">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 6h16M4 12h16M4 18h16"/></svg>
    </button>

    <button class="av-search-trigger" type="button" data-av-palette-open
            aria-label="Search pages and commands">
      <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
        <circle cx="10.5" cy="10.5" r="6.5"/><path d="M15.5 15.5L21 21"/>
      </svg>
      <span class="av-search-trigger__text">Search…</span>
      <span class="av-search-trigger__kbd"><kbd class="av-kbd">Ctrl</kbd><kbd class="av-kbd">K</kbd></span>
    </button>
  </div>

  <div class="av-topbar__end">
    <button class="av-btn av-btn--ghost av-btn--icon" type="button"
            data-av-theme-toggle data-av-tooltip="Toggle colour mode" aria-label="Toggle colour mode">
      <svg class="av-icon av-mode-icon--light" aria-hidden="true" viewBox="0 0 24 24">
        <circle cx="12" cy="12" r="4"/>
        <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/>
      </svg>
      <svg class="av-icon av-mode-icon--dark" aria-hidden="true" viewBox="0 0 24 24">
        <path d="M21 13A8.5 8.5 0 1 1 11 3a7 7 0 0 0 10 10z"/>
      </svg>
    </button>

    <div class="av-dropdown">
      <button class="av-topbar__profile" type="button" data-av-dropdown-toggle
              aria-expanded="false" aria-haspopup="menu" aria-label="Account menu">
        <span class="av-avatar" aria-hidden="true">JC</span>
        <span class="av-topbar__profile-meta" aria-hidden="true">
          <span class="av-topbar__profile-name">Jane Cooper</span><br>
          <span class="av-topbar__profile-role">Administrator</span>
        </span>
      </button>
      <ul class="av-dropdown__menu" role="menu">
        <li class="av-dropdown__label" role="presentation">Signed in as jane@…</li>
        <li role="none"><a class="av-dropdown__item" href="/settings" role="menuitem">Settings</a></li>
        <li class="av-dropdown__divider" role="separator"></li>
        <li role="none">
          <a class="av-dropdown__item av-dropdown__item--danger" href="/logout" role="menuitem">Sign out</a>
        </li>
      </ul>
    </div>
  </div>
</header>

Dropdowns are data-av-dropdown-toggle on a .av-dropdown wrapper. There is no Bootstrap in this build and no data-bs-toggle; initDropdowns() delegates from document, so markup that arrives later already works.

The divider is a <li class="av-dropdown__divider" role="separator">, not an <hr>. A menu is a list, and an <hr> between list items is not.

A control that acts on the open panel rather than dismissing it opts out of close-on-click with data-av-dropdown-keep. Without it, "mark all read" closes the panel before its own result can be seen.


Step 4 — Page header and KPI cards ​

html
<div class="av-page-header">
  <div>
    <ol class="av-breadcrumb" aria-label="Breadcrumb">
      <li><a href="/">Home</a></li>
      <li aria-current="page">Orders</li>
    </ol>
    <h1 class="av-page-header__title">Orders</h1>
    <p class="av-page-header__subtitle">1,284 orders this month · +12.4% vs last month</p>
  </div>
  <div class="av-page-header__actions">
    <button class="av-btn av-btn--outline" type="button">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
        <path d="M12 3v12M7 11l5 5 5-5M4 21h16"/>
      </svg>
      Export
    </button>
    <a class="av-btn av-btn--primary" href="/orders/new">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg>
      New order
    </a>
  </div>
</div>

<div class="av-grid av-grid--stats" style="margin-block-end: var(--av-space-4)">
  <div class="av-stat-card">
    <div class="av-stat-card__head">
      <span class="av-stat-card__label">Revenue</span>
      <span class="av-stat-card__icon">
        <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
          <path d="M17 7H9.5a3.5 3.5 0 0 0 0 7H14a3.5 3.5 0 0 1 0 7H6M4 10h8M4 14h8"/>
        </svg>
      </span>
    </div>
    <div class="av-stat-card__value" data-av-money="4825000">€48,250.00</div>
    <div class="av-stat-card__foot">
      <span class="av-trend av-trend--up">
        <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
          <path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/>
        </svg>
        12.4%
      </span>
      <span>vs last month</span>
    </div>
  </div>
  <!-- repeat for Orders, Customers, Refunds -->
</div>

av-grid av-grid--stats is the row. There is no row/col-* system here — the utility layer is deliberately small, and the stat row is a named grid rather than four column classes you have to keep in step. See Layout Anatomy.

Money is written as integer minor units. data-av-money="4825000" with the formatted string as the no-JS fallback in the element's own text; initMoney() reformats it at runtime through Intl.NumberFormat. Never format currency by hand — the thousands separator, the symbol position and the decimal mark all change with the locale.

The top accent bar on a stat card is driven off the icon's role modifier with :has(), so the bar and the icon cannot disagree.


Step 5 — A chart ​

html
<div class="av-card" style="margin-block-end: var(--av-space-4)">
  <div class="av-card__header">
    <div>
      <h2 class="av-card__title">Revenue over time</h2>
      <p class="av-card__subtitle">This period against the one before it</p>
    </div>
    <span class="av-badge av-badge--success-soft">+12.4%</span>
  </div>
  <div class="av-card__body">
    <div data-av-chart
         style="--av-chart-height: 320px"
         data-av-chart-options='{
           "type": "area",
           "series": [{ "name": "Revenue", "data": [31, 40, 28, 51, 42, 62, 74] }],
           "categories": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
           "stroke": { "curve": "smooth", "width": 2 }
         }'></div>
  </div>
</div>

Charts are ApexCharts, vendored locally and lazy-loaded when the element scrolls into view. Colours come from the resolved tokens, so a preset or mode change re-themes the chart in place.

Two things will bite you:

  • labels must be absent, not undefined. Apex reads .length off it while laying out a bar and throws. The same applies to formatter: an explicit undefined replaces Apex's default rather than falling back to it, and radar calls the value straight out of a forEach with no guard.
  • More than two series takes the categorical ramp. The brand pair is two colours and Apex cycles it, so a third series silently repeats the first.

data-av-chart-src and data-av-chart-series do not exist in this build. Earlier versions of this page showed both. The runtime reads data-av-chart-options and data-av-chart-fallback, and nothing else — fetch the data yourself and write the options attribute, or render it server-side. Full options: Charts.


Step 6 — A data grid ​

Start with real server-rendered rows so the page works before JavaScript arrives:

html
<div class="av-card">
  <div class="av-table-wrap">
    <table class="av-table">
      <caption class="av-visually-hidden">Orders, filterable and sortable</caption>
      <thead>
        <tr>
          <th scope="col" class="av-table__check">
            <input type="checkbox" data-av-grid-select-all aria-label="Select all visible orders">
          </th>
          <th scope="col">Order</th>
          <th scope="col">Customer</th>
          <th scope="col">Status</th>
          <th scope="col" class="av-table__num">Total</th>
          <th scope="col">Date</th>
          <th scope="col" class="av-table__actions-cell">
            <span class="av-visually-hidden">Actions</span>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr data-av-status="paid">
          <td class="av-table__check">
            <input type="checkbox" data-av-grid-row-check aria-label="Select order #1042">
          </td>
          <th scope="row" data-av-key="order" data-av-value="1042">
            <a href="/orders/1042">#1042</a>
          </th>
          <td data-av-key="customer" data-av-value="Sarah Kim">
            <span class="av-table__person">
              <span class="av-avatar av-avatar--sm" aria-hidden="true">SK</span>
              <span>
                <span class="av-table__link">Sarah Kim</span><br>
                <span class="av-table__person-meta">sarah@northwind.io</span>
              </span>
            </span>
          </td>
          <td data-av-key="status" data-av-value="Paid">
            <span class="av-badge av-badge--success-soft">Paid</span>
          </td>
          <td class="av-table__num" data-av-key="total" data-av-value="1240">€1,240.00</td>
          <td data-av-key="date" data-av-value="2026-08-12">
            <time datetime="2026-08-12">12 Aug 2026</time>
          </td>
          <td class="av-table__actions-cell">
            <div class="av-dropdown">
              <button class="av-btn av-btn--ghost av-btn--icon" style="--av-btn-height: 30px"
                      type="button" data-av-dropdown-toggle aria-expanded="false"
                      aria-haspopup="menu" aria-label="Actions for order #1042">
                <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
                  <circle cx="12" cy="5" r="1"/><circle cx="12" cy="12" r="1"/><circle cx="12" cy="19" r="1"/>
                </svg>
              </button>
              <ul class="av-dropdown__menu" role="menu">
                <li role="none"><a class="av-dropdown__item" href="/orders/1042" role="menuitem">View order</a></li>
                <li class="av-dropdown__divider" role="separator"></li>
                <li role="none">
                  <button class="av-dropdown__item av-dropdown__item--danger" type="button" role="menuitem">
                    Delete
                  </button>
                </li>
              </ul>
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

data-av-value is what the grid sorts on, not the cell's text. €1,240.00 sorts as a string between €1,199 and €13; 1240 sorts as a number. Dates are the same problem in a different costume — the visible 12 Aug 2026 and the sortable 2026-08-12 are different strings on purpose.

.av-table-wrap is the scroll container, and it needs min-inline-size: 0 on any grid or flex ancestor. A grid item's automatic minimum size is its content's min-content width, so a wide table grows its track past the viewport instead of scrolling inside its own wrapper.

A dropdown inside a scroll container cannot be rescued with z-index — overflow does not consult it. initDropdowns promotes the menu to a popover on first open, which puts it in the top layer, above every stacking context and outside every scroll container, with no change to your markup.


Step 7 — Adding your own behaviour ​

The runtime exposes theme, toast, confirm, loading, a11y, utils, on, emit, init, destroy and version on window.AdminVora. Bind your own behaviour to a data- hook and use the event bus to talk to the rest of the page:

js
// app.js
document.addEventListener('change', async (event) => {
  const el = event.target.closest('[data-av-order-status] select');
  if (!el) return;

  const root = el.closest('[data-av-order-status]');
  const { orderStatusUrl: url, orderStatusId: id, orderStatusCurrent: current } = root.dataset;

  root.classList.add('is-busy');
  try {
    const res = await fetch(url, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content
      },
      body: JSON.stringify({ status: el.value })
    });
    if (!res.ok) throw new Error(res.statusText);

    AdminVora.toast.success('Status updated');
    AdminVora.emit('order:status-changed', { id, status: el.value });
  } catch {
    AdminVora.toast.error('Could not update status');
    el.value = current;
  } finally {
    root.classList.remove('is-busy');
  }
});
html
<div data-av-order-status
     data-av-order-status-url="/api/orders/1042/status"
     data-av-order-status-id="1042"
     data-av-order-status-current="paid">
  <select class="av-select">
    <option value="pending">Pending</option>
    <option value="paid" selected>Paid</option>
    <option value="shipped">Shipped</option>
  </select>
</div>

Delegating from document is not a shortcut here — it is the pattern the built-in modules use for anything that must survive markup arriving later, and it needs no re-scan at all.

After a client-side navigation ​

js
// Turbo, htmx, or your router's after-render hook
AdminVora.destroy(oldRoot);   // dispose vendor instances — a chart holds a resize observer
AdminVora.init(newRoot);      // bind modules in the subtree that changed

destroy() releases the data-av-init claims so markup that is moved rather than destroyed can be bound again on arrival. It does not detach listeners; those go with the elements.

There is no way to register your own module with the runtime. Bind your own behaviour after av:content fires, and use the data-av-* hooks, init(root) and destroy(root) for everything the runtime already provides.


Checklist before you call it done ​

  • [ ] Page renders and is usable with JS disabled
  • [ ] Every interactive element is reachable with Tab and shows a focus ring
  • [ ] Toggle dark mode — check contrast on badges, muted text, and chart gridlines
  • [ ] Toggle RTL (dir="rtl") — check icon direction and table alignment
  • [ ] Resize to 320 px — no horizontal scroll on either the document or .av-content
  • [ ] Every image has alt (empty alt="" for decorative), every icon has aria-hidden="true"
  • [ ] The active menu row carries av-menu__item--active and aria-current="page"

Read next: CLI & Scripts.

Documentation for @creativeigniter/adminvora