The shared structure of every admin area and dashboard, with a side menu and the content.
<div data-mount="expanded"></div>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/admin-shell.css";
import { enhance } from "capsomer/behavior/admin-shell";
enhance();import "capsomer/tokens.css";
import "capsomer/admin-shell.css";
import { AdminShell } from "capsomer/react/admin-shell";Usage
<div class="cap-admin" data-cap="admin-shell" data-variant="owner">
[the site header: components/site-header's markup, with Search, Inbox, the theme button and the avatar]
<nav class="cap-admin-strip" aria-label="Apps">
<ul class="cap-admin-strip-group">
<li><a class="cap-admin-tile" href="https://portal.dustinedwards.info/" aria-current="true"><svg class="cap-admin-logo">[the app's mark]</svg>[tip]</a></li>
<li><a class="cap-admin-tile" href="https://desk.dustinedwards.info/" aria-label="Carrel Desk, 2 need you"><svg class="cap-admin-logo">…</svg><span class="cap-count cap-admin-badge" data-tone="need" aria-hidden="true">2</span>[tip]</a></li>
[dustinedwards.info, germomics, Foxhound, Foxing, Capsomer, in that order]
</ul>
</nav>
<nav class="cap-admin-menu" id="cap-admin-menu" aria-label="Sections">
<button type="button" class="cap-admin-collapse" data-cap-part="menu-toggle" aria-label="Collapse menu" aria-expanded="true" aria-controls="cap-admin-menu">[icon]<span class="cap-admin-label">Collapse menu</span><span class="cap-keys"><kbd>[</kbd></span><span class="cap-admin-tip cap-popover" data-variant="tooltip" data-side="right" data-offset="12" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-admin-tip-text">Collapse menu</span></span></button>
<div class="cap-admin-group" role="group" aria-labelledby="g-watch">
<div class="cap-admin-group-label" id="g-watch">Watch</div>
<a href="/" aria-current="page">[icon]<span>Overview</span> <span class="cap-count cap-admin-count"></span></a>
<a href="/queue" aria-label="Queue, 5 blocked">[icon]<span class="cap-admin-label">Queue</span><span class="cap-admin-tip cap-popover" data-variant="tooltip" data-side="right" data-offset="12" popover="manual" role="tooltip" aria-hidden="true"><span class="cap-admin-tip-text">Queue</span></span> <span class="cap-count cap-admin-count" data-tone="need">5</span></a>
</div>
</nav>
<main class="cap-admin-main" id="cap-main" tabindex="-1">
<div class="cap-admin-bar">
<div class="cap-admin-bar-text"><nav class="cap-admin-trail" aria-label="Breadcrumb"><ol><li><a href="/components">Components</a></li><li><span aria-current="page">Shell</span></li></ol></nav>[below the top level only]<span class="cap-admin-fresh">Updated <time datetime="…">6 minutes ago</time> · refreshes itself</span><div class="cap-admin-bar-status">[status]</div></div>
<div class="cap-admin-actions">[actions]<button type="button" class="cap-admin-btn" data-cap-part="refresh" aria-label="Refresh">[icon][tip]</button></div>
</div>
<div class="cap-admin-page">[the view]</div>
</main>
<nav class="cap-site-tabs" aria-label="Sections">[up to five links]</nav>
</div>Examples
Menu collapsed to icons: every icon where it was, a divider between groups, counts at the icon's corner
<div data-mount="collapsed"></div>
Collapsed: a menu icon's name shown beside it, over every panel
<div data-mount="collapsed-tip"></div>
A page below the top level: the top bar shows the trail
<div data-mount="trail"></div>
A strip tile showing its name and key
<div data-mount="tip"></div>
The header's account menu: this app, View site and Help, sign out
<div data-mount="account"></div>
A user's dashboard: no strip, a 288px menu, the business and product switchers in the header
<div data-mount="user"></div>
A user's dashboard, the menu collapsed to icons
<div data-mount="user-collapsed"></div>
A reader's area: the user variant with a reading column
<div data-mount="reader"></div>
Comfortable density
<div data-mount="comfortable"></div>
Page transitions: the content cross-fades between pages, the strip and menu stay put
<div data-mount="transition"></div>
An app whose routes set their own tab titles: documentTitle={false} leaves them alone
<div data-mount="own-title"></div>
Phone width: the header's one row and the bottom bar of five tabs
<div data-mount="phone"></div>
Phone width: the menu button's sheet holds the apps and every page, Sign out pinned
<div data-mount="phone-sheet"></div>
Phone width: a count past 99 on a tab says 99+
<div data-mount="phone-counts"></div>
An app that passes only its own name: the strip still shows all seven apps with their marks
<div data-mount="minimal"></div>
Foxhound's mark: today's x and two alternatives, until Dustin picks
<div data-mount="foxhound-marks"></div>
API reference
AdminShell
| Prop | Type | Required | Does |
|---|---|---|---|
variant | "owner" | "user" | "owner" (your admin): the strip of the family's apps, then a 232px menu. "user" (a customer's own dashboard): no strip and a 288px menu, so the page starts at the same left edge in both. | |
app | FamilyAppId | The family app this is. The strip lists every family app (FAMILY_APPS) in one order with this one marked, and the header's logo is its mark and name unless logo is given. | |
badges | Partial<Record<FamilyAppId, AdminBadge>> | Other apps' badges, from Capsid's one "what needs the owner" answer. The current app's is never shown. | |
title | string | The app's name, for the tab title and the sheet. Default: the family app's. Set it only outside the family. | |
apps | AdminApp[] | The strip for a site outside the family. Admin areas pass app. | |
nav | AdminEntry[] | Yes | |
pathname | string | The address you are on (React Router's useLocation().pathname). Given, every entry without its own current is marked from it, and page defaults to the current entry's label. | |
page | string | The page being shown: the tab title "<page> · <app>", and the last step of the trail. | |
documentTitle | boolean | Whether the shell writes the tab title from page and title. Default true. False leaves document.title to the app's routes; title still names the logo, the sheet and its groups. | |
trail | AdminCrumb[] | The levels above the page. Given, the top bar shows the trail ("Components / Shell"); a top-level page has none, so the bar never repeats the page's own heading. | |
tabs | AdminEntry[] | The phone's bottom bar: up to five of this app's top pages, no More. Default: the first five. | |
navLabel | string | ||
logo | HeaderLogo | The header (components/site-header): the site's logo, its band, a switcher (a dashboard's business and product), and its extras. Search and Inbox are the header's first two extras; Help is a row of the account menu. | |
letterhead | boolean | The family letterhead (components/site-header): the band as tall as the site's public pages, its second row holding where you are and View site; search is the header's search icon and field. | |
search | { action: string; label: string; name?: string; suggest?: Suggest } | ||
band | "dark" | ||
translucent | boolean | ||
switchers | HeaderSwitcher[] | ||
extras | HeaderExtra[] | ||
onSearch | () => void | ||
searchShortcut | string | ||
inbox | { count?: number; countNote?: string; href?: string; onOpen?: () => void; shortcut?: string; } | ||
onHelp | () => void | ||
viewSite | string | The account menu's View site row. | |
account | AdminAccount | ||
updated | { at: number | Date | string; auto?: boolean } | The page bar: the trail and how fresh the data is on the left; then the page-wide controls and Refresh (shown when the page can refresh), last. updated is the one freshness line every app shows: "Updated 6 minutes ago", with "· refreshes itself" when auto. status is anything else true of the page. | |
status | ReactNode | ||
actions | ReactNode | ||
onRefresh | () => void | ||
refreshing | boolean | ||
refreshShortcut | string | ||
themePrefKey | string | The theme button's localStorage key ("cap-theme" by default), and the single key the app lets the header bind to it ("T"); leave it out where the app binds its own. | |
themeKey | string | ||
themeCookie | SiteHeaderProps["themeCookie"] | Passed to the site header: where the theme choice is kept besides this browser (a cookie, the account), the server's answer, the no-script theme form, and whether the header hydrates. | |
onThemeSave | SiteHeaderProps["onThemeSave"] | ||
themeInitial | SiteHeaderProps["themeInitial"] | ||
themeAction | SiteHeaderProps["themeAction"] | ||
hydrate | SiteHeaderProps["hydrate"] | ||
prefKey | string | ||
jumpKeys | boolean | G then 1 to 9 opens the app in that place (the key sequence of GitHub and Linear; Ctrl and a digit belong to the browser's tabs); on by default, and off with the shortcuts switch. false turns it off for this app alone. | |
collapseKey | string | false | The menu's collapse key, shown on the collapse control and in its tip. The shell binds it (never while a person types, or with single-key shortcuts off); false shows no key and binds none. | |
renderLink | (props: LinkProps) => ReactNode | ||
mainProps | Omit<ComponentPropsWithRef<"main">, "id" | "className" | "tabIndex" | "children"> | The main region's own ref and handlers (an app that scrolls to a row, say). Its id, class and tab stop are the shell's. | |
collapsed | boolean | ||
onCollapsedChange | (collapsed: boolean) => void | ||
transition | boolean | Page transitions (View Transitions API): the content cross-fades between pages while the header, strip and menu stay put. Off by default; reduced motion and browsers without the API get no animation. The app wraps its page change in startPageTransition (a flushSync inside). | |
children | ReactNode | Yes |
Functions
| Function | Signature | Does |
|---|---|---|
pageTransitionsOn | (shell?: HTMLElement | null): boolean | |
startPageTransition | (update: () => void | Promise<void>, shell?: HTMLElement | null | undefined): Promise<void> | |
setMenu | (shell: HTMLElement, collapsed: boolean, remember?: boolean): void | |
toggleMenu | (shell: HTMLElement): void | |
jumpTarget | (armed: { at: number; }, e: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "altKey" | "target">, apps: readonly { href: string; current?: boolean | undefined; }[], now?: number): string | null | |
isCollapseKey | (e: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "altKey" | "target" | "defaultPrevented" | "isComposing">, key?: string): boolean | The menu's collapse key ([ by default): the shell binds it, so every app behaves the same. Never with a modifier, while a person types (a field, a contenteditable, a code editor), during IME composition, after another handler took the key, or while single-key shortcuts are off. |
currentEntryId | (pathname: string, entries: readonly MatchEntry[]): string | undefined | |
enhance | (root?: ParentNode): () => void | Attaches to every [data-cap="admin-shell"] under root that is not attached yet. Returns a function that detaches them all. |
CSS variables
| Variable | Default |
|---|---|
--_bubble | var(--space-5) |
--_gw | 20px |
--_gx | calc(50% - 10px) |
--admin-hover | color-mix(in srgb, var(--ground), var(--text) 10%) |
--admin-hover-edge | var(--line-strong) |
--admin-menu | var(--admin-menu-open) |
--admin-menu-collapsed | calc(var(--rail-w-collapsed) + var(--space-6)) |
--admin-menu-open | calc(var(--rail-w) + var(--space-6)) |
--admin-pill | var(--accent-12) |
--admin-pill-fg | var(--ground) |
--admin-row-pad | calc((var(--admin-menu-collapsed) - 2 * var(--space-3) - var(--space-5)) / 2) |
--admin-strip | var(--rail-w-collapsed) |
--admin-strip-bg | color-mix(in srgb, var(--ground), var(--text) 7%) |
--admin-tile | 36px |
--admin-top | var(--header-h) |
--header-bg | set by the page |
Parts and data attributes
| Class | Is |
|---|---|
.cap-admin | the root |
.cap-admin-actions | a part |
.cap-admin-badge | a part |
.cap-admin-bar | a part |
.cap-admin-bar-text | a part |
.cap-admin-btn | a part |
.cap-admin-collapse | a part |
.cap-admin-count | a part |
.cap-admin-group | a part |
.cap-admin-group-label | a part |
.cap-admin-icon | a part |
.cap-admin-label | a part |
.cap-admin-letter | a part |
.cap-admin-logo | a part |
.cap-admin-main | a part |
.cap-admin-menu | a part |
.cap-admin-page | a part |
.cap-admin-strip | a part |
.cap-admin-strip-group | a part |
.cap-admin-tile | a part |
.cap-admin-tip | a part |
.cap-admin-trail | a part |
| Attribute | Values |
|---|---|
data-measure | reading |
data-menu | collapsed |
data-mono | present or absent |
data-standalone | present or absent |
data-tone | present or absent |
data-transition | page |
data-variant | letterhead user |
data-width | narrow page |
| State | Read from |
|---|---|
:active | the platform |
:focus | the platform |
:hover | the platform |
[aria-current="page"] | an attribute |
[aria-current="true"] | an attribute |
Accessibility
| Key | Does |
|---|---|
| Tab | The skip link, the header (logo, switchers, Search, Inbox, the theme, the avatar), the strip's apps, the menu (the collapse control first), the main region |
| Enter or Space on the collapse control | Collapses or expands the menu |
| Esc | Hides a shown name; closes the account menu and returns focus to the avatar; closes the sheet and returns focus to the menu button |
| G, then 1 to 9 | Opens the app in that place |
| Enter or Space on the avatar | Opens the account menu; focus moves to its first item, Up and Down move between items |
| Any link, with transitions on | Moves to the page as without them; the transition does not move focus |
[ | Collapses or expands the menu (not while typing, or with single-key shortcuts off) |
- The header is the
banner. The strip, the menu and the phone bar are navigation landmarks with their own names ("Apps", "Sections"); the menu and the bar are never displayed together. - Every strip control has an accessible name that contains what it shows; a badge says what it counts in the name ("Carrel Desk, 2 AI drafts waiting").
- Names of the current app and page are
aria-current(trueon the tile,pageon the menu link), and not conveyed by color alone (a dark fill, plus an outline in forced colors). - Menu text, counts and the pill reach their contrast in both themes; the tests measure the painted colors.