sander-ui
v1.1.0
Published
A modern React component library built with TypeScript and CSS Modules
Maintainers
Readme
🧩 sander-ui
A modern, accessible React component library — lightweight, themeable, and ready for production.
🌐 Live Demo · 📖 Storybook Docs · 🔗 reactdev.io
✨ Why sander-ui?
- Accessibility-first, and enforced — Built on native HTML elements (
<dialog>,<details>) with full ARIA support, keyboard navigation, and focus management. Every story is audited with axe on each CI run and a violation fails the build; keyboard and focus behaviour has its own interaction tests. - Zero-runtime styling — CSS Modules + CSS Custom Properties. Scoped styles with zero CSS-in-JS overhead.
- Zero dependencies — Nothing but React as a peer. Icons are inline SVG and all animations are pure CSS — no heavy libraries needed.
- 56 production-ready components — Forms, feedback, data display, navigation and layout, with compound component patterns (e.g. Modal + ModalHeader/Body/Footer).
- Design token system — Comprehensive CSS custom properties for colors, typography, spacing, radii, shadows, and transitions — ready for theming via simple variable overrides.
- Dark mode, with nothing to wire up — Follows
prefers-color-schemeon import, or takes an explicitdata-themewhen you want a switch. No component knows a theme exists, and the contrast of both palettes is unit-tested. - Server Components ready — Interactive components declare
"use client"themselves, so they drop straight into the Next.js App Router. The 17 that need no hooks stay server-renderable and ship no JavaScript at all. - Tree-shakeable — ES module exports with subpath imports (
sander-ui/button) for optimal bundle size. - TypeScript-first — Strict mode, full type definitions, and clear prop interfaces for every component.
- Refs reach the DOM — Every component forwards its
refto the element it renders, typed to that element, soreact-hook-form, focus management and measurement all work without a wrapper. See Refs. - Composes with your router —
asChildhands a component's styling, ARIA and handlers to your own element, so aButtoncan be a Next.js or React Router link rather than wrap one. See Composition.
📦 Installation
npm install sander-uiPeer dependencies: React 18 or 19
🚀 Usage
Import components and the stylesheet:
import { Button, Input, Modal } from "sander-ui";
import "sander-ui/styles.css";You can also import individual components via subpath exports for optimal tree-shaking:
import { Button } from "sander-ui/button";
import { Modal, ModalHeader, ModalBody, ModalFooter } from "sander-ui/modal";Use them in your app:
function App() {
return (
<div>
<Button variant="primary" size="md" onClick={() => alert("Clicked!")}>
Click me
</Button>
<Input label="Email" placeholder="[email protected]" />
</div>
);
}Many components support compound patterns for flexible composition:
<Card>
<CardHeader>
<Heading as="h3">Card Title</Heading>
</CardHeader>
<CardBody>
<Text>Card content goes here.</Text>
</CardBody>
<CardFooter>
<Button variant="primary">Save</Button>
</CardFooter>
</Card>▲ Next.js and Server Components
Nothing to configure. Every component that uses a hook carries "use client" into the published bundle, so importing it from a Server Component — the default in the App Router — just works:
// app/page.tsx — a Server Component
import { Card, CardBody, Heading, Text } from "sander-ui";
import { Select } from "sander-ui/select";
export default function Page() {
return (
<Card>
<CardBody>
<Heading as="h1">Orders</Heading> {/* rendered on the server, no JS */}
<Text color="muted">Pick a delivery speed.</Text>
<Select options={options} label="Speed" /> {/* its own client boundary */}
</CardBody>
</Card>
);
}The 17 components that need no hooks are deliberately not marked, so they render on the server and ship no JavaScript: Alert · Badge · Button · Card · Container · Heading · IconButton · Link · Pagination · Progress · Radio · Skeleton · Spinner · Stepper · Table · Text · Timeline.
The barrel is not marked either, so import { Text } from "sander-ui" stays server-renderable even though the same barrel re-exports Select.
Which side of the line a component falls on is not a list anyone maintains: src/rsc.test.ts derives it from the features each component actually uses, then checks the built dist/ — a directive that is missing and one that should not be there both fail the build. This matters because bundlers strip module-level directives during transform, so a directive in a source file proves nothing about what shipped.
🗂️ Components
📝 Form
Field · Button · IconButton · Input · Textarea · NumberInput · SearchInput · PasswordInput · Select · Combobox · DatePicker · TimePicker · ColorPicker · Checkbox · Radio · Switch · Slider · Rating · OtpInput · FileUpload · TagInput · ToggleGroup
💬 Feedback
Alert · Toast · Progress · Spinner · Skeleton
📊 Data Display
Avatar · Badge · Table · Tooltip · Accordion · Timeline · Carousel
🧭 Navigation
Navbar · Sidebar · NavigationMenu · Menubar · Tabs · Breadcrumbs · Pagination · Dropdown · Command · Link · Stepper · BackToTop
📐 Layout
Container · Card · Modal · Drawer · Popover · ScrollArea · Splitter · Toolbar · Heading · Text
🔗 Link
An inline anchor. It takes the font size, weight and line height of the text around it and owns only its colour and underline, so it drops into a paragraph without disturbing the line — including breaking across it:
<Text as="p">
Audited with <Link href="https://github.com/dequelabs/axe-core" external>axe-core</Link> on every commit.
</Text>underline defaults to always, because colour on its own does not mark a link up for a reader who cannot separate it from the body text (WCAG 1.4.1). Save hover and none for navigation and standalone links, where position already does that work.
variant picks the colour: primary for a link in prose, default for one that is the whole line, muted for supporting text, inverse for a dark surface, and inherit to take the colour of whatever it sits inside. size follows the surrounding text unless you set it, and icon places a leading glyph sized to the text.
external opens the link in a new tab and says so: it sets target="_blank", adds an arrow, and appends "(opens in a new tab)" to the accessible name. Pass hideExternalIcon to drop the arrow and keep the announcement. A rel of your own is extended rather than replaced, so rel="nofollow" on an external link comes out as nofollow noopener noreferrer.
A router's link component has to own the anchor to intercept the click, so asChild styles the child instead of rendering one:
<Link asChild variant="default">
<NextLink href="/docs">Read the docs</NextLink>
</Link>The child keeps everything of its own — href, target and rel stay where you wrote them — and receives the link's styling on top. See Composition for what asChild merges, and which other components take it.
🪜 Stepper
Progress through an ordered sequence — a checkout, an onboarding flow, a multi-page form. It renders as an <ol>, so assistive tech announces the position in the sequence, and marks the step in progress with aria-current="step":
<Stepper
activeStep={1}
steps={[
{ label: "Cart" },
{ label: "Delivery", description: "Address and times" },
{ label: "Payment" },
{ label: "Confirmation" },
]}
/>Everything before activeStep counts as complete and everything after it as upcoming. A step can set its own status to override that, which is the only way to mark one as error — a failed step keeps its place in the sequence rather than reading as done. Completed and failed steps carry a word for screen readers as well as a tick or a triangle, since shape and colour do not survive on their own, and optional appends "(optional)" the same way.
Passing onStepChange renders each step as a button, for a wizard whose earlier steps can be revisited. Completed steps and the current one can be picked; allowSkipAhead opens up the rest, and disabled on a step closes it off either way. Leave onStepChange off for a read-only progress indicator.
orientation switches between left-to-right and top-to-bottom, variant="dots" drops the numbers for a compact trail, and the marker size, connector thickness, connector colour and the space between steps are custom properties:
<Stepper style={{ "--stepper-marker-size": "2.75rem", "--stepper-gap": "3rem" }} />🏷️ Field
Field puts one label, hint and error treatment around any control. It works out the id, aria-describedby and aria-invalid and hands them to its child, so the wiring is identical whichever input goes inside — and anything the control was already described by is kept:
<Field label="Email" hint="We only use it to send receipts." error={error} required>
<Input type="email" />
</Field>Leave the child's own label and error props off when you wrap it: the field owns both. For a group of controls with no single element to point a label at, as="fieldset" renders a <legend> and describes the group instead:
<Field as="fieldset" label="Billing period" hint="Annual saves 20%.">
<RadioGroup name="billing" value={value} onChange={setValue} options={options} />
</Field>⏰ TimePicker · 🎨 ColorPicker · 🔍 SearchInput · 🔒 PasswordInput
<TimePicker label="Doors open" min="09:00" max="17:00" step={15} value={time} onChange={setTime} />
<ColorPicker label="Brand colour" value={colour} onChange={setColour} swatches={brand} />
<SearchInput label="Search" debounce={300} onSearch={run} loading={pending} />
<PasswordInput label="New password" strengthMeter autoComplete="new-password" />TimePicker exchanges HH:MM on a 24-hour clock — the shape a native <input type="time"> uses, so nothing depends on a Date or a time zone — while the display follows the locale. The field stays typeable: 930, 9:30, 9.30 and 9:30 pm all land, and anything unreadable snaps back rather than being silently reinterpreted. ColorPicker exchanges lowercase #rrggbb, names every preset (a swatch says nothing out loud), and draws the tick on the chosen swatch in whichever of black or white can be seen on it. SearchInput renders as type="search" for the platform's searchbox role, with Enter to search, Escape to clear, and an announced busy state — a spinner is invisible to a screen reader. PasswordInput swaps the input's type rather than masking by hand, so password managers still recognise the field; its strength meter states the score in words and treats the coloured bars as decoration. Scoring is a hint for the person typing, not a security control — pass strength to replace it.
⌘ Command
Command is a searchable list of commands — the ⌘K palette. Focus stays in the field while the highlight moves with aria-activedescendant, which is what lets a single keystroke both filter and navigate:
<CommandDialog open={open} onClose={() => setOpen(false)} label="Command palette" onSelect={run}>
<CommandInput placeholder="Type a command or search…" />
<CommandList>
<CommandEmpty>No commands match that search.</CommandEmpty>
<CommandGroup heading="Actions">
<CommandItem value="New file" shortcut="⌘N" onSelect={createFile}>New file</CommandItem>
<CommandItem value="Upload" keywords={["import", "attach"]}>Upload a file</CommandItem>
</CommandGroup>
</CommandList>
</CommandDialog>value is both the text the query is matched against and what onSelect receives; keywords widen what finds an item without cluttering its label, and filter replaces the matching outright. Groups fold away once every item in them is filtered out, and the result count is announced as the list rewrites itself. Drop CommandDialog for Command to embed the same palette inline — the dialog only adds the top layer, the focus trap and Escape, all of which come from the native <dialog>.
🎠 Carousel · 🕓 Timeline · 🏷️ TagInput · 🔘 ToggleGroup
<Carousel aria-label="Product highlights" autoPlay loop>
<CarouselSlide>…</CarouselSlide>
</Carousel>
<Timeline>
<TimelineItem variant="success" title="Deployed" date="12 March" dateTime="2026-03-12">
Shipped to production.
</TimelineItem>
</Timeline>
<TagInput label="Recipients" value={tags} onChange={setTags} max={5} />
<ToggleGroup aria-label="Text alignment" options={alignment} value={align} onChange={setAlign} />Carousel names itself a landmark once you give it an aria-label, pauses auto-rotation on hover and focus, never starts it for a visitor who asked for reduced motion, and makes off-screen slides inert so nothing inside them can be tabbed to. Timeline renders an <ol> so the sequence is announced, with its markers treated as decoration — pair date with dateTime to keep the timestamp machine-readable. TagInput commits on Enter or a delimiter, takes the last tag back on Backspace, splits a pasted list, and announces every change. ToggleGroup is a radio group when type="single" and a toolbar of toggle buttons when type="multiple"; either way it is one tab stop, so name it with aria-label.
🧭 Navbar · Sidebar · NavigationMenu
The app shell. Navbar is the bar across the top, Sidebar the column down the side, and NavigationMenu a row of links where some of them open a panel:
<Navbar sticky blur>
<NavbarBrand href="/">🧩 sander-ui</NavbarBrand>
<NavbarContent>
<NavbarItem href="/components" active>Components</NavbarItem>
<NavbarItem href="/docs">Docs</NavbarItem>
</NavbarContent>
<NavbarActions>
<Button size="sm">Get started</Button>
</NavbarActions>
<NavbarToggle />
<NavbarMenu>
<NavbarItem href="/components" active>Components</NavbarItem>
<NavbarItem href="/docs">Docs</NavbarItem>
</NavbarMenu>
</Navbar>Navbar renders a <header> around a <nav>, so the banner and the navigation are both landmarks, and marks the open page with aria-current="page". It collapses on its own width rather than the viewport's — a container query, so a bar inside a narrow column behaves like one on a narrow phone. Below 768px the links give way to NavbarToggle and NavbarMenu, a disclosure wired up with aria-expanded and aria-controls and closed by Esc, which hands focus back to the button that opened it. Only one of the two lists is ever in the accessibility tree, so both can carry the same label.
<Sidebar collapsed={collapsed}>
<SidebarHeader>🧩 sander-ui</SidebarHeader>
<SidebarNav aria-label="Main">
<SidebarGroup label="Workspace">
<SidebarItem href="/overview" icon={<Star />} active>Overview</SidebarItem>
<SidebarItem href="/tasks" icon={<Check />} badge={12}>Tasks</SidebarItem>
</SidebarGroup>
</SidebarNav>
<SidebarFooter>
<Avatar name="Sander van Rijsoort" size="sm" />
</SidebarFooter>
</Sidebar>SidebarNav is the landmark and owns the list; a group nests a list of its own inside it and labels it, which is what a grouped navigation is — so a screen reader reaches "Workspace, list, 4 items" rather than four unattributed links. collapsed narrows it to a rail of icons and keeps every label in the accessibility tree, because an icon on its own says nothing; the same markup serves both widths. Widths are custom properties (--sidebar-width, --sidebar-collapsed-width). It has no opinion about small screens — put it inside a Drawer, which brings the focus trap and Esc with it.
<NavigationMenu aria-label="Main">
<NavigationMenuItem>
<NavigationMenuTrigger>Products</NavigationMenuTrigger>
<NavigationMenuContent>
<NavigationMenuLink href="/components" description="Fifty-two of them" active>
Components
</NavigationMenuLink>
<NavigationMenuLink href="/tokens">Design tokens</NavigationMenuLink>
</NavigationMenuContent>
</NavigationMenuItem>
<NavigationMenuItem>
<NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
</NavigationMenuItem>
</NavigationMenu>NavigationMenu is a set of disclosures, not a menu: each trigger is a button that says what it controls, and the panels hold ordinary links. role="menu" would promise application-style keys the web has never had here and would take the links out of a screen reader's list of them. The arrow keys move along the bar, ↓ opens a panel and steps into it, and Esc closes it — including when the panel was opened by hovering and the focus is nowhere near it, which is what WCAG 1.4.13 asks for. Hovering (openOnHover, on by default) is ignored for touch, where a tap would open and close in one gesture. Panels line up with their trigger by align, and widen with --navigation-menu-content-width.
⌘ Menubar · 🧰 Toolbar
Two composites that are one tab stop each, because a bar of twelve controls should not cost twelve presses of Tab to get past:
<Menubar aria-label="Main">
<MenubarMenu>
<MenubarTrigger>File</MenubarTrigger>
<MenubarContent>
<MenubarItem shortcut="⌘N" onSelect={newFile}>New file</MenubarItem>
<MenubarSeparator />
<MenubarItem checked={wrap} onSelect={() => setWrap(!wrap)}>Wrap lines</MenubarItem>
<MenubarItem disabled>Save as…</MenubarItem>
</MenubarContent>
</MenubarMenu>
</Menubar>Menubar is the one place in the library where role="menubar" and role="menu" are the right answer: the items are commands the application carries out, so the application-style keys those roles promise are the keys that are actually there — ←/→ between menus, ↓ to open one, ↑ to open it at its last item, and the arrows carrying an open menu along the bar. Compare NavigationMenu, whose panels contain links and which is therefore built from disclosures instead. Items become menuitemcheckbox the moment you pass checked, a disabled item stays focusable so it is not a mystery, and shortcut is decoration — a reminder of a binding the application owns, not something the menu listens for.
<Toolbar aria-label="Text formatting">
<ToolbarGroup>
<ToolbarButton iconOnly aria-label="Bold" pressed={bold} onClick={toggleBold}>B</ToolbarButton>
<ToolbarButton iconOnly aria-label="Italic" pressed={italic} onClick={toggleItalic}>I</ToolbarButton>
</ToolbarGroup>
<ToolbarSeparator />
<ToolbarButton>Insert link</ToolbarButton>
</Toolbar>Toolbar works with any focusable child, not only ToolbarButton — it finds the controls in the DOM rather than requiring its own components, so a Button or a plain link takes part too. Widgets that run their own keyboard handling are left alone: a Dropdown's menu items and a ToggleGroup's roving tabindex stay theirs, so opening a menu inside a toolbar does not turn its items into stops on the row. The control last used keeps the tab stop, so Tab away and back returns to where you were rather than to the start.
📜 ScrollArea · ↔️ Splitter · ⬆️ BackToTop
<ScrollArea aria-label="Release notes" fade scrollbars="hover">
<ReleaseNotes />
</ScrollArea>
<Splitter label="Sidebar width" defaultSize={30} min={15} max={60}>
<Files />
<Editor />
</Splitter>
<BackToTop threshold={400} />ScrollArea styles the scrollbar and leaves the scrolling to the platform — nothing here replaces it with JavaScript, so the wheel, the keyboard, momentum and find-in-page all behave as they should. A scrollable region has to be reachable by keyboard or its contents cannot be read without a pointer, so it is a tab stop by default and reports as a named group. fade softens whichever edge the content carries on past, drawn as a mask on the scrolling box so it stays put while the content moves under it, and it is what makes scrollbars="hidden" honest. The ref is the scrolling element itself, so scrollTop and scrollTo are yours.
Splitter is the window splitter pattern: the handle is a focusable separator reporting aria-valuenow, aria-valuemin and aria-valuemax, so it moves with the arrow keys, jumps to either end with Home and End, and collapses and restores with Enter. Sizes are percentages, so a layout survives a resize of whatever it sits in. BackToTop watches the window, or a panel through containerRef; it honours the visitor's motion preference, and hides by leaving the tab order rather than unmounting under the focus.
See the components in action at the 🌐 Live Demo, or browse interactive examples and full prop documentation at the 📖 Storybook.
🎨 Theming
All visual decisions are centralized in CSS custom properties, making theming as simple as overriding variables:
:root {
--color-primary: #6366f1;
--color-primary-hover: #4f46e5;
--font-family: "Inter", system-ui, sans-serif;
--radius-md: 0.5rem;
}Available token categories: colors, typography (Outfit), spacing, border radius, shadows, transitions, and z-index.
🌗 Dark mode
Dark mode needs no setup: importing the stylesheet is enough, and the library follows the operating system through prefers-color-scheme. To offer a switch instead, set data-theme on the document element — it wins over the system preference in both directions:
document.documentElement.dataset.theme = "dark"; // or "light"
delete document.documentElement.dataset.theme; // back to following the systemSet it during server rendering, or in a blocking inline script, to avoid a flash of the wrong theme on first paint.
No component knows a theme exists. Every colour resolves through a token, so a theme is a set of values rather than a set of components — which is also why your own overrides are inherited by both themes. Override inside the same three entry points to change only one:
:root {
--color-primary: #6366f1; /* both themes */
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-primary: #818cf8; /* the system-dark theme only */
}
}
:root[data-theme="dark"] {
--color-primary: #818cf8; /* and the explicitly-dark theme */
}Two things are worth knowing before you write those overrides:
A fill and the same hue used as text cannot be the same token. White ink needs a fill no lighter than about 18% luminance, while that hue used as text on a dark page has to be lighter than that to clear 4.5:1 — no single teal or red satisfies both. So --color-primary and --color-error are the fill (and the border, and the focus ring), while --color-primary-text and --color-error-text are the same hue when it has to be read. Change both if you re-brand.
Brand and semantic fills are identical in both themes. Only neutrals, surfaces, tinted containers and text tones flip, so a teal button is the same teal at midnight. What flips is listed in one place, at the bottom of src/styles/_tokens.css.
The roles a surface can take are --color-surface (the page), --color-surface-raised (cards, menus, inputs, popovers), --color-surface-sunken, and --color-surface-inverse for the deliberately opposite plane a tooltip uses. Paint with those rather than with --color-white, which stays white in the dark.
Contrast is not asserted, it is tested: src/styles/tokens.test.ts checks the WCAG ratios both themes have to hold — including the states no story renders — and fails if a token defined for light has no dark counterpart. The Theming/Themes story renders a cross-section of the library in each theme, which is what puts the dark palette under axe on every CI run. Every other story can be viewed in either theme from the toolbar.
🧬 Composition
A router's Link owns its own anchor so it can intercept the click. That leaves nowhere to put a Button: you cannot nest a <button> inside the anchor — two interactive elements inside one another is invalid HTML and reads as two controls — and wrapping the button in a link is the same problem the other way round.
asChild hands the component's styling, ARIA and handlers to your element instead, so one element does both jobs:
import Link from "next/link";
<Button asChild variant="primary">
<Link href="/docs">Read the docs</Link>
</Button>
// <a class="button primary" href="/docs"><span class="content">Read the docs</span></a>It is on the interactive components, where the router case actually comes up:
Button · IconButton · Link · SidebarItem · NavbarItem · NavbarBrand · NavigationMenuLink · DropdownItem · MenubarItem · ToolbarButton · DropdownTrigger · PopoverTrigger
Layout components take an as prop instead — Card, Container, Text, Heading, Sidebar — since there is no third-party element to defer to, only a tag name to choose.
What gets merged. Your element wins where the two disagree, because you are the more specific author — with three exceptions that would otherwise be silent bugs:
| | |
| --- | --- |
| Event handlers | Both run, yours first. Nothing is dropped. |
| className, style | Merged. Yours wins on a property both set. |
| ref | Composed, so a ref already on the child survives. |
| Everything else | Yours wins. A prop you leave undefined is not an override, so the role the component needs is not stripped by an unset one. |
The component's own markup comes with it. A SidebarItem keeps its icon and badge, a loading Button keeps the spinner and the span that holds its width — your children are dropped into place rather than replacing the structure the CSS rests on.
Disabled works on an anchor. disabled is not an attribute there, so a disabled Button asChild reports aria-disabled, leaves the tab order, and has its pointer events taken by the stylesheet — which is what actually stops the click, since your handler runs first and cannot be called off.
Passing anything but a single element throws where you wrote it, rather than leaving a class missing somewhere downstream.
🔗 Refs
Every component forwards its ref, typed to the element it lands on, so the node is yours without a wrapper around it:
const email = useRef<HTMLInputElement>(null);
const dialog = useRef<HTMLDialogElement>(null);
<Input ref={email} label="Email" />
<Modal ref={dialog} open={open} onClose={close}>…</Modal>That covers what a form library needs — react-hook-form's Controller can register the control, and focusing the first invalid field after a failed submit works — as well as measuring a panel or scrolling a region into view.
Which element you get is the one the component's other props land on, not always its outermost node. The cases worth knowing:
| Component | The ref is |
| --- | --- |
| Switch | the <button role="switch">, not the <label> around it |
| Table | the <table>, not the scroll wrapper |
| Select, Combobox, DatePicker, TimePicker, ColorPicker | the wrapper the label and the field sit in. className and any other prop you pass go to the control inside it — the trigger or the input — because that is the part you style and the part that takes focus |
| Modal, Drawer, CommandDialog | the <dialog>, and null while closed, because nothing is mounted then |
| SidebarItem, NavbarItem, DropdownItem | the control it renders — its <a> or its <button> |
| Field, Rating | whichever root it renders: a <div>, or a <fieldset> |
| Card, Text, Container, Sidebar | whatever as names, typed as HTMLElement |
| Tooltip | the wrapper, not the trigger you passed as children |
| PopoverTrigger, DropdownTrigger with asChild | your own element |
Popover and ToastProvider take no ref: both render no element of their own, and the refs worth having sit on their children.
Components that keep a ref of their own on the same node — a <dialog> they call showModal() on, a list they measure — compose the two, so neither is lost. src/refs.test.ts checks every exported component forwards a ref, derived from the export list so a new component is covered the day it is added; the Internal/Refs story checks each one reaches the right element.
📋 Forms
Give a field a name and it renders the control that carries its value, so it is
submitted, validated and reset like any other — including Select, Combobox,
DatePicker, TimePicker, ColorPicker and Rating, none of which is a native
control on the outside:
<form onSubmit={handleSubmit}>
<Select name="fruit" label="Favorite fruit" options={fruits} required />
<button type="submit">Save</button>
<button type="reset">Reset</button>
</form>required is enforced by the browser, and a reset puts the field back to its
defaultValue — or to empty if it had none. A field you drive yourself with
value is yours to reset, the same as a native one.
Those six take either a value or a defaultValue; the rest — Slider,
TagInput, NumberInput, OtpInput, ToggleGroup, Switch, Tabs,
Pagination — take a required value and are always yours to drive. The split
is deliberate, and src/value.contract.test.tsx holds every one of them to it.
Anything else you pass goes to the control inside — the trigger or the input:
onBlur and onFocus for react-hook-form, data-* for a test hook,
aria-describedby for your own hint. A handler you pass runs before the
component's own, and preventDefault() from it stops the component reacting at
all — the same bargain asChild strikes, and the same function
behind both. Rating is the exception: it renders a set of radios rather than one
control, so there is no single element for a stray prop to land on.
♿ Accessibility
Accessibility is checked automatically rather than asserted. Every story runs through axe on each CI run, and any violation fails the build — so a regression cannot be merged. Text colours meet the WCAG AA 4.5:1 contrast ratio.
Because axe only inspects the rendered DOM, keyboard and focus behaviour is covered by separate interaction tests:
| Component | Verified behaviour |
| --- | --- |
| Tabs | Roving tabindex, ←/→, Home/End, wrapping |
| Select | ↓ to open, arrow navigation, typeahead, Enter to select, Esc to close, aria-activedescendant |
| Dropdown | ↓ opens and focuses the first item, arrow navigation, Home/End, Esc restores focus to the trigger |
| Modal, Drawer | Focus starts inside, the rest of the page is inert, Esc closes and returns focus to the trigger |
| Popover | Focus moves in on open, and a dismissal by the browser is reflected back into React. Built on the native Popover API, so the top layer, Esc, outside-click dismissal and the focus return are the platform's — those need trusted events, so they are covered by a Playwright pass rather than the story tests |
| Switch | Space and Enter toggle |
| Checkbox | Space toggles, clicking the label toggles |
| Radio | Arrow keys move focus and selection together |
| Pagination | aria-current="page", keyboard activation of every control |
| NumberInput | ↑/↓ step, PageUp/PageDown take the large step, Home/End jump to the bounds, letters are refused, values clamp on blur |
| OtpInput | Typing advances, Backspace clears then walks back, arrow keys move between fields, a pasted code spreads across them |
| FileUpload | The input stays in the tab order behind the drop zone, and rejected files are announced through an alert |
| Slider | Tab reachability, and the value, readout and aria-valuetext stay in sync |
| Combobox | Typing filters and announces the count, arrow navigation, Enter selects, Esc closes then clears, disabled options are stepped over |
| DatePicker | Clicking the field opens the calendar without taking focus, ↓ hands focus to the grid, arrow keys walk it, Home/End reach the week's bounds, PageUp/PageDown change month, Enter takes the date, Esc closes and restores focus |
| Rating | Only the checked star is a tab stop, and the group reports as a named radiogroup |
| NavigationMenu | ←/→ move along the bar with wrapping, Home/End reach its ends, ↓ opens a panel and focuses its first link, Tab walks the panel, Esc closes it and restores focus to the trigger, and moving along the bar closes a panel left open |
| Navbar | The toggle reports aria-expanded and points at the panel it controls, and Esc closes the panel and returns focus to the toggle |
| Sidebar | Labels survive the collapsed rail, groups keep their headings, and a disabled item stays a link that Tab skips |
| Menubar | One tab stop, ←/→ between menus with wrapping, ↓ and ↑ open a menu at its first or last item, the arrows carry an open menu along the bar, Home/End inside a menu stay inside it, and Esc closes and returns focus to the trigger |
| Toolbar | One tab stop, arrow keys along the row with Home/End, the control last used keeps the stop, and a nested Dropdown's items are not part of the row |
| Splitter | The handle reports aria-valuenow against its bounds, arrow keys move it by step and Shift by largeStep, Home/End reach the bounds and stop there, Enter collapses and restores |
| ScrollArea | The region is a tab stop, so it can be scrolled without a pointer |
| BackToTop | Hidden until the scroll passes the threshold, and out of the accessibility tree until it is |
Labelling
Components that render a visible label from the label prop are named automatically. Without one, pass aria-label yourself:
<Switch aria-label="Dark mode" checked={on} onChange={setOn} />
<Checkbox aria-label="Accept terms and conditions" />
<Slider aria-label="Volume" value={volume} onChange={setVolume} />Select is the strict case: its trigger is a role="combobox", which by specification takes no accessible name from its content — a placeholder does not name it. Give it either a visible label or an aria-label:
<Select label="Favorite fruit" options={fruits} />
<Select aria-label="Favorite fruit" placeholder="Choose a fruit..." options={fruits} />The same applies to Combobox, to the radiogroup that Rating renders, and to
PopoverContent, which is a role="dialog":
<Combobox aria-label="Country" placeholder="Search countries" options={countries} />
<Rating aria-label="Rating" value={score} onChange={setScore} />
<PopoverContent aria-label="Rename project">…</PopoverContent>PopoverContent can take its name from a heading inside it instead:
<PopoverContent aria-labelledby="billing-heading">
<Heading as="h3" id="billing-heading">Billing period</Heading>
</PopoverContent>🛠️ Development
npm install
npm run storybook # component workshop on :6006
npx vitest run # axe audit + keyboard interaction tests (real Chromium)
npm run lint
npm run buildThe test suite drives a real browser via Playwright, since <dialog> focus trapping, inertness and animation-driven unmounting cannot be exercised faithfully in a simulated DOM. Install the browser once with npx playwright install chromium.
🚢 Releasing
Publishing is triggered by a version tag, never by a merge to master — merging only runs the checks.
npm version minor # bumps package.json, commits, creates the tag
git push origin master
git push origin refs/tags/v0.3.0 # this push publishesThe release workflow verifies the tag matches package.json, re-runs lint, build and the full test suite, then publishes to npm through Trusted Publishing (OIDC) with signed provenance — no npm token is stored anywhere.
Push the tag by its full ref as shown.
--follow-tagswould push every unpushed annotated tag in the repository at once, and each one matchingv*would start its own release run.
Before bumping the version, move everything under Unreleased in CHANGELOG.md into a heading for the version being released.
🌐 Browser Support
Supports all modern browsers (Chrome, Firefox, Safari, Edge). Requires support for CSS Custom Properties and ES Modules.
📄 Changelog
Notable changes are recorded in CHANGELOG.md, in Keep a Changelog format.
📄 License
MIT © Sander van Rijsoort
