@primitiv-ui/web
v0.2.15
Published
Primitiv's headless components as standard custom elements: light DOM, no framework, and no runtime dependencies beyond Prism, which loads only for a code block and only the grammars it uses. Works in plain HTML, server-rendered stacks, React, Vue, Angula
Readme
@primitiv-ui/web
Primitiv's headless components as standard custom elements: light DOM, no
framework and no runtime dependencies beyond
@primitiv-ui/core. They work in a plain HTML page, any
server-rendered stack (HTMX, Rails, Django, Laravel, Spring …), and inside
React, Vue, Angular or any other framework.
Status: published. Tabs, Accordion, Collapsible, Modal, Popover, Tooltip, Dropdown, Context Menu, Toggle Group, Segmented Control, Radio Card, Checkbox Card, Slider, Split Button, Listbox, Select, Combobox, Navigation Menu, Tree, Stepper, Miller Columns, Table's expandable rows and Code Block so far. See RFC 0033 for the design.
Components
| Component | Elements | Change event | First release |
|---|---|---|---|
| Tabs | primitiv-tabs, -list, -trigger, -content | primitiv-tabs-change | 0.1.42 |
| Accordion | primitiv-accordion, -item, -trigger, -content, -trigger-icon | primitiv-accordion-change | 0.1.44 |
| Collapsible | primitiv-collapsible, -trigger, -content, -trigger-icon | primitiv-collapsible-change | 0.1.47 |
| Modal | primitiv-modal, -trigger, -content, -title, -description, -close | primitiv-modal-change | 0.1.54 |
| Popover | primitiv-popover, -trigger, -anchor, -content, -title, -description, -close | primitiv-popover-change | 0.1.55 |
| Tooltip | primitiv-tooltip, -provider, -trigger, -content, -arrow | primitiv-tooltip-change | 0.1.56 |
| Dropdown | primitiv-dropdown, -trigger, -content, -item, -checkbox-item, -radio-group, -radio-item, -item-indicator, -group, -label, -separator, -sub, -sub-trigger, -sub-content | primitiv-dropdown-change, -sub-change, -select, -checked-change, -value-change | 0.1.57 |
| Context Menu | primitiv-context-menu, and the same thirteen parts as Dropdown under primitiv-context-menu- | primitiv-context-menu-change, -sub-change, -select, -checked-change, -value-change | 0.1.58 |
| Toggle Group | primitiv-toggle-group, -item | primitiv-toggle-group-change | 0.1.59 |
| Segmented Control | primitiv-segmented-control, -item | primitiv-segmented-control-change | 0.1.60 |
| Radio Card | primitiv-radio-card, -item, -indicator | primitiv-radio-card-change | 0.1.61 |
| Checkbox Card | primitiv-checkbox-card, -indicator | primitiv-checkbox-card-change | 0.1.61 |
| Slider | primitiv-slider, -track, -range, -thumb | primitiv-slider-change, primitiv-slider-commit | 0.1.61 |
| Split Button | primitiv-split-button, -action (its menu is a nested primitiv-dropdown) | the Dropdown's | 0.1.62 |
| Listbox | primitiv-listbox, -option, -group, -group-label | primitiv-listbox-change | 0.2.1 |
| Select | primitiv-select, -trigger, -value, -content, -item, -item-indicator, -group, -separator | primitiv-select-change, -open-change | 0.2.1 |
| Combobox | primitiv-combobox, -input, -content, -item, -empty | primitiv-combobox-change, -open-change, -query-change | 0.2.1 |
| Navigation Menu | primitiv-navigation-menu, -list, -item, -trigger, -content, -viewport, -indicator, -link | primitiv-navigation-menu-change | 0.2.10 |
| Tree | primitiv-tree, -item, -branch, -branch-control, -branch-content, -branch-indicator, -selection-path | primitiv-tree-change, primitiv-tree-expanded-change | 0.2.11 |
| Stepper | primitiv-stepper, -list, -step, -panel | primitiv-stepper-change | 0.2.12 |
| Miller Columns | primitiv-miller-columns, -tree, -column, -item, -item-indicator, -resize-handle, -preview-panel | primitiv-miller-columns-change | 0.2.13 |
| Table | primitiv-table-expand-trigger | primitiv-table-expand-change | 0.2.14 |
| Code Block | primitiv-code-block, -copy | primitiv-code-block-copy, -highlight | 0.2.15 (copy: 0.2.14) |
Use it
No build step — one script tag per component defines that component's elements and nothing else:
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/tabs.js"></script>
<primitiv-tabs value="overview">
<primitiv-tabs-list label="Account sections">
<primitiv-tabs-trigger value="overview"><button type="button">Overview</button></primitiv-tabs-trigger>
<primitiv-tabs-trigger value="billing"><button type="button">Billing</button></primitiv-tabs-trigger>
</primitiv-tabs-list>
<primitiv-tabs-content value="overview">…</primitiv-tabs-content>
<primitiv-tabs-content value="billing" hidden>…</primitiv-tabs-content>
</primitiv-tabs>With a bundler — import a define entry once, anywhere:
import "@primitiv-ui/web/define/tabs"; // one component's elements
import "@primitiv-ui/web/define"; // or every elementEach dist/cdn/<component>.js imports the code components share from
dist/cdn/chunks/ by a relative URL, so a page that loads two components
downloads it once. dist/primitiv-web.js is the alternative: every element in
one file. Per-component files ship from 0.1.43.
The main entry (@primitiv-ui/web, /tabs, /accordion, /collapsible,
/modal, /popover, /tooltip, /dropdown, /context-menu, /toggle-group, /segmented-control, /radio-card, /checkbox-card, /slider, /split-button, /listbox, /select, /combobox, /navigation-menu, /tree) exports the classes and defineTabs(registry?) /
defineAccordion(registry?) / defineCollapsible(registry?) /
defineModal(registry?) / definePopover(registry?) / defineTooltip(registry?) /
defineDropdown(registry?) / defineContextMenu(registry?) /
defineToggleGroup(registry?) / defineSegmentedControl(registry?) /
defineRadioCard(registry?) / defineCheckboxCard(registry?) / defineSlider(registry?) / defineSplitButton(registry?) /
defineListbox(registry?) / defineSelect(registry?) / defineCombobox(registry?) /
defineNavigationMenu(registry?) / defineTree(registry?) / defineStepper(registry?) / defineMillerColumns(registry?) / defineTable(registry?) / defineCodeBlock(registry?) with no side
effects.
Render hidden on inactive panels yourself. Until the module loads, CSS
cannot tell which panel is active, so markup that omits it shows every panel.
Listen with primitiv-tabs-change (bubbles, cancelable, detail: { value,
index }) — call preventDefault() to veto a change — and primitiv-tabs-show
on a panel as it becomes active, for lazy loading.
Accordion
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/accordion.js"></script>
<primitiv-accordion value="shipping">
<primitiv-accordion-item value="shipping">
<h3>
<primitiv-accordion-trigger><button type="button">Shipping</button></primitiv-accordion-trigger>
</h3>
<primitiv-accordion-content>Free on orders over £50.</primitiv-accordion-content>
</primitiv-accordion-item>
<primitiv-accordion-item value="returns">
<h3>
<primitiv-accordion-trigger><button type="button">Returns</button></primitiv-accordion-trigger>
</h3>
<primitiv-accordion-content hidden>30 days, no questions asked.</primitiv-accordion-content>
</primitiv-accordion-item>
</primitiv-accordion>valuelists the open items, separated by spaces (so item values cannot contain whitespace), and is reflected as items toggle.multiplelets more than one be open;orientation="horizontal"switches the arrow pair. Thevalueproperty reads as an array and accepts an array or a string.- The heading is yours. Wrap each trigger in a real
<h2>–<h6>at the level your outline needs; there is no header element. force-mounton a panel keeps it unhidden so styles can animate it, hiding it witharia-hiddenwhile closed instead — the registry stylesheet needs it.role="none"on a panel opts it out of being a region landmark, for an accordion with many items.- Listen with
primitiv-accordion-change(bubbles, cancelable,detail: { value }, every item open afterwards) andprimitiv-accordion-showon a panel as its item opens. Renderhiddenon closed panels yourself, as for Tabs.
Collapsible
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/collapsible.js"></script>
<primitiv-collapsible>
<primitiv-collapsible-trigger><button type="button">Shipping details</button></primitiv-collapsible-trigger>
<primitiv-collapsible-content hidden>Orders ship within two business days.</primitiv-collapsible-content>
</primitiv-collapsible>openis the state, a boolean attribute reflected as the user toggles, and theopenproperty reads and sets it.disabledon the root keeps the button focusable but stops it toggling.collapsed-heighton the panel shows a clamped preview while closed (the read-more pattern): a bare number is pixels, anything else a CSS length. It is published as--primitiv-collapsible-collapsed-heightwithdata-clamped="true", and the panel is never hidden, since the preview is real content.force-mountkeeps a closed panel unhidden for your own animation, witharia-hiddeninstead.- Listen with
primitiv-collapsible-change(bubbles, cancelable,detail: { open }) andprimitiv-collapsible-showon the panel as it opens. Renderhiddenon a closed panel yourself, as for Tabs.
Modal
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/modal.js"></script>
<primitiv-modal>
<primitiv-modal-trigger><button type="button">Edit profile</button></primitiv-modal-trigger>
<primitiv-modal-content>
<dialog>
<primitiv-modal-title><h2>Edit profile</h2></primitiv-modal-title>
<primitiv-modal-description><p>Changes apply to every workspace.</p></primitiv-modal-description>
<primitiv-modal-close><button type="button">Done</button></primitiv-modal-close>
</dialog>
</primitiv-modal-content>
</primitiv-modal>- It is a native
<dialog>, opened withshowModal(): the browser supplies the top layer, the::backdropand the inert page. The element adds the Tab wrap, closing on Escape and on a backdrop press, and the ARIA wiring —aria-haspopup,aria-expandedandaria-controlson the trigger's button,aria-labelledby/aria-describedbyfrom the title's heading and the description's paragraph. Focus returns to the trigger on close. openon the root is the state, reflected as the user opens and dismisses it; theopenproperty reads and sets it, and setting it is not announced. Leaveopenoff the<dialog>itself — the root opens it modally, and reopens modally one that arrives with it (a history snapshot).- Several triggers and close buttons are fine. There is no overlay element:
style
::backdrop. - Listen with
primitiv-modal-change(bubbles, cancelable,detail: { open }), fired before every user-driven change — trigger, close, Escape, a backdrop press, a<form method="dialog">— sopreventDefault()keeps a dirty form open.
Popover
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/popover.js"></script>
<primitiv-popover>
<primitiv-popover-trigger><button type="button">Share</button></primitiv-popover-trigger>
<primitiv-popover-content popover="auto">
<primitiv-popover-title><h2>Share this page</h2></primitiv-popover-title>
<primitiv-popover-description><p>Anyone with the link can view it.</p></primitiv-popover-description>
<primitiv-popover-close><button type="button">Done</button></primitiv-popover-close>
</primitiv-popover-content>
</primitiv-popover>- It is a native
popover="auto"panel: the browser supplies the top layer and light dismiss. The element addsrole="dialog"and the trigger's ARIA, moves focus into the panel on open, and closes it on Escape with focus back on the trigger. Writepopover="auto"yourself so the panel is hidden before the script loads. - No anchor wiring. The panel is shown with its trigger as its source (or
the element inside
<primitiv-popover-anchor>), which makes it the implicit anchor, so CSS anchor positioning (position-area) places it with noanchor-name/position-anchorpair. openon the root is the state; theopenproperty reads and sets it. Listen withprimitiv-popover-change(bubbles, cancelable,detail: { open }), fired before every user-driven change, a light dismiss included.
Tooltip
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/tooltip.js"></script>
<primitiv-tooltip>
<primitiv-tooltip-trigger><button type="button">Save</button></primitiv-tooltip-trigger>
<primitiv-tooltip-content popover="manual">
Saves your work
<primitiv-tooltip-arrow></primitiv-tooltip-arrow>
</primitiv-tooltip-content>
</primitiv-tooltip>- It opens on hover after
delay-duration(700 ms) and on focus at once, and closes when the pointer leaves (after a short grace period, so the pointer can reach the bubble —disable-hoverable-contentturns that off), on blur, on Escape and on a press outside. The element gives the bubblerole="tooltip"and the trigger's buttonaria-describedby. - It is a native
popover="manual"in the top layer, shown with the trigger as its source, so CSS anchor positioning places it with noanchor-name/position-anchorpair. Writepopover="manual"yourself so the bubble is hidden before the script loads. - Moving from one trigger to the next opens each next tooltip at once (the
skip delay, 300 ms). Tooltips inside a
<primitiv-tooltip-provider>share itsdelay-durationandskip-delay-duration; the rest share a document-wide window. openon the root is the state; theopenproperty reads and sets it. Listen withprimitiv-tooltip-change(bubbles, cancelable,detail: { open }), fired before every user-driven change.
Dropdown
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/dropdown.js"></script>
<primitiv-dropdown>
<primitiv-dropdown-trigger><button type="button">Options</button></primitiv-dropdown-trigger>
<primitiv-dropdown-content popover="auto">
<primitiv-dropdown-item><li>Copy</li></primitiv-dropdown-item>
<primitiv-dropdown-checkbox-item checked><li>Show grid</li></primitiv-dropdown-checkbox-item>
<primitiv-dropdown-sub>
<primitiv-dropdown-sub-trigger><li>Share</li></primitiv-dropdown-sub-trigger>
<primitiv-dropdown-sub-content popover="auto">
<primitiv-dropdown-item><li>Email</li></primitiv-dropdown-item>
</primitiv-dropdown-sub-content>
</primitiv-dropdown-sub>
</primitiv-dropdown-content>
</primitiv-dropdown>- A menu button over a native
popover="auto", anchored to its trigger with no wiring. It opens focused on the first item; the arrows, Home and End move, Enter and Space choose, typing finds an item, and Escape, a press outside or a chosen item closes it with focus back on the trigger. - Each row wraps the element you write (an
<li>, or a link), which gets its menu role. Close every<li>: the HTML parser ends an open<li>at the next one, custom elements or not.disabledon a row skips it. - State is attributes:
openon the root and on each<primitiv-dropdown-sub>,checkedon a checkbox item (indeterminatefor mixed),valueon a radio group. Each change fires a cancelable event first; listen forprimitiv-dropdown-selecton an item to act on it, and cancel it to keep the menu open.
Context Menu
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/context-menu.js"></script>
<primitiv-context-menu>
<primitiv-context-menu-trigger>Right-click here</primitiv-context-menu-trigger>
<primitiv-context-menu-content popover="manual">
<primitiv-context-menu-item><li>Copy</li></primitiv-context-menu-item>
<primitiv-context-menu-item><li>Delete</li></primitiv-context-menu-item>
</primitiv-context-menu-content>
</primitiv-context-menu>- Dropdown's menu, opened at the pointer: a right-click in the
<primitiv-context-menu-trigger>region — which is the region itself, not a wrapper — or the keyboard's context-menu key on it opens the menu, with the same rows, keyboard, typeahead, submenus, attributes and events (prefixedprimitiv-context-menu-).disabledon the region leaves the browser its own menu. - The menu is
popover="manual": anautoone would close on the right-click's own release. Escape, a press outside and a chosen item close it, and its submenus close with it. - Position it from
--primitiv-context-menu-x/-y, the pointer's position the element publishes on the menu — the one style the elements write, since a point cannot be an anchor:left: var(--primitiv-context-menu-x); top: var(--primitiv-context-menu-y). The registry stylesheet does this.
Toggle Group
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/toggle-group.js"></script>
<primitiv-toggle-group type="multiple" value="bold" aria-label="Formatting">
<primitiv-toggle-group-item value="bold"><button type="button">Bold</button></primitiv-toggle-group-item>
<primitiv-toggle-group-item value="italic"><button type="button">Italic</button></primitiv-toggle-group-item>
</primitiv-toggle-group>- The root is the
role="group": name it witharia-label. Each item wraps the<button>you write, which getsaria-pressedanddata-state="on" | "off". valuelists the pressed items, separated by spaces.type="multiple"lets items toggle independently; without it the group is single, and pressing the pressed item clears it.primitiv-toggle-group-changefires first, with every item pressed afterwards, and is cancelable.- One Tab stop for the group, on the item focus last moved to, else the
first pressed item, else the first. The arrows move focus without pressing,
skipping
disableditems; Enter and Space toggle. - A form control with a
name. Each pressed value submits under it, as same-named checkboxes do, through hidden inputs the group keeps inside itself; a form reset restores the values it first rendered with. Optional: without anamethe group takes no part in forms.
Segmented Control
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/segmented-control.js"></script>
<primitiv-segmented-control value="week" aria-label="Range">
<primitiv-segmented-control-item value="day"><button type="button">Day</button></primitiv-segmented-control-item>
<primitiv-segmented-control-item value="week"><button type="button">Week</button></primitiv-segmented-control-item>
</primitiv-segmented-control>- The root is the
role="radiogroup": name it witharia-label. Each segment wraps the<button>you write, which getsrole="radio",aria-checkedanddata-state="checked" | "unchecked". valueis the selected segment, and a selected segment never lets go — unlike a toggle group, the control cannot be emptied by the user.primitiv-segmented-control-changefires first, with the segment selected afterwards, and is cancelable.disabledon the root disables every segment.- One Tab stop for the control, on the selected segment, else the first
enabled one. The arrows move focus and selection, skipping
disabledsegments and wrapping; Enter and Space are the button's own click. - A form control with a
name. The selected value submits under it, as a checked radio does: nothing while none is selected or the control isdisabled, and a form reset restores the first value. Optional. For an "All" choice, give a segmentvalue="".
Breadcrumb Overflow
No element of its own: write Breadcrumb's markup with the collapsed crumbs in a
<primitiv-dropdown>, each <a> wrapped in a <primitiv-dropdown-item>, and
load dist/cdn/dropdown.js. The menu anchors to its ... trigger with no
anchor-name, and Enter on a hidden crumb follows its link.
Radio Card
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/radio-card.js"></script>
<primitiv-radio-card value="pro" aria-label="Plan">
<primitiv-radio-card-item value="basic">
<button type="button"><primitiv-radio-card-indicator></primitiv-radio-card-indicator>Basic</button>
</primitiv-radio-card-item>
<primitiv-radio-card-item value="pro">
<button type="button"><primitiv-radio-card-indicator></primitiv-radio-card-indicator>Pro</button>
</primitiv-radio-card-item>
</primitiv-radio-card>- The same radio group as Segmented Control, laid out as cards: the root is
the
role="radiogroup", each card's<button>arole="radio", andvaluethe selected card. It lays nothing out — put the cards in a Stack or grid. orientationdefaults toboth: all four arrows move the selection, for cards that wrap into a grid.horizontalorverticalkeeps to one pair and writesaria-orientation.- A form control with a
name, exactly as Segmented Control: the selected value submits under it, and a form reset restores the first value. Optional. <primitiv-radio-card-indicator>anywhere in a card ishiddenwhile the card is unchecked, unless it carriesforce-mount(so a stylesheet can animate it fromdata-state).
Checkbox Card
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/checkbox-card.js"></script>
<primitiv-checkbox-card checked>
<button type="button"><primitiv-checkbox-card-indicator></primitiv-checkbox-card-indicator>Email updates</button>
</primitiv-checkbox-card>- One card, one checkbox: it decorates the
<button>you write as arole="checkbox".checkedis present, absent, or"indeterminate"(aria-checked="mixed"); a press on a mixed card checks it.primitiv-checkbox-card-changefires first, withcheckedafterwards, and is cancelable. - Cards are independent and each is its own tab stop; Space and Enter are the button's own click. Like the radio card, it submits nothing with a form.
Slider
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/slider.js"></script>
<primitiv-slider value="20 80" min="0" max="100" name="price">
<primitiv-slider-track><primitiv-slider-range></primitiv-slider-range></primitiv-slider-track>
<primitiv-slider-thumb aria-label="Minimum"></primitiv-slider-thumb>
<primitiv-slider-thumb aria-label="Maximum"></primitiv-slider-thumb>
</primitiv-slider>valuelists one number per thumb, separated by spaces; the number of thumbs is the number of thumb elements.step,min-steps-between-thumbs,orientation,invertedanddisabledwork as on React's Slider.- Each thumb is the
role="slider": name it, not the root. The arrows step, Page Up / Page Down step ten, Home / End jump; a press on the slider jumps the nearest thumb and drags it. - Positions are written inline. Each thumb and the range get
position: absoluteand their inset along the track as a percentage, as React's Slider does — the one style the elements write, since it is the value. - Two events:
primitiv-slider-changebefore each change (cancelable, on every step of a drag),primitiv-slider-commitonce the interaction ends. namesubmits it with a form: the slider keeps one hidden<input>per value inside itself (name[]for several thumbs).
Split Button
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/split-button.js"></script>
<primitiv-split-button>
<primitiv-split-button-action><button type="button">Save</button></primitiv-split-button-action>
<primitiv-dropdown>
<primitiv-dropdown-trigger><button type="button" aria-label="Change save action">⌄</button></primitiv-dropdown-trigger>
<primitiv-dropdown-content popover="auto">
<primitiv-dropdown-item><li>Save and close</li></primitiv-dropdown-item>
<primitiv-dropdown-item><li>Save as draft</li></primitiv-dropdown-item>
</primitiv-dropdown-content>
</primitiv-dropdown>
</primitiv-split-button>- The menu is a Dropdown: its
openstate and events are<primitiv-dropdown>'s, andsplit-button.jsdefines the Dropdown elements too. The group is therole="group", mirroring the menu indata-state. - ArrowDown on the action opens the menu on its first item, through the
trigger, so the cancelable
primitiv-dropdown-changestill fires. - The trigger is named for you: unless its
<button>hasaria-labeloraria-labelledby, it getsaria-labelledby="<trigger id> <action id>". disabledon the group disables both halves; put it on<primitiv-split-button-action>or<primitiv-dropdown-trigger>to disable one half alone.
TypeScript — opt into the tag map so DOM queries return the element classes:
import type {} from "@primitiv-ui/web/tags" (npm only).
React 19 JSX — import type {} from "@primitiv-ui/web/react" types the
tags, their attributes and the raw onprimitiv-tabs-change handler (npm only).
React 19 passes a custom element's event prop to addEventListener exactly as
written, which is why the prop reads that way; most React projects want
@primitiv-ui/react, whose onValueChange is the idiomatic name.
Vue 3 templates — import type {} from "@primitiv-ui/web/vue" lets
vue-tsc check each tag's attributes and its @primitiv-tabs-change handler
(npm only). Also tell Vue's compiler the tags are custom elements:
compilerOptions.isCustomElement: (tag) => tag.startsWith("primitiv-").
Svelte 5 templates — import type {} from "@primitiv-ui/web/svelte" lets
svelte-check check each tag's attributes and its onprimitiv-tabs-change
handler (npm only). Svelte needs no other setup: it renders unknown tags as
custom elements already.
Angular — add CUSTOM_ELEMENTS_SCHEMA to the component's schemas, bind
the value as a property ([value]="value()"), the other options as attributes
([attr.activation-mode]="mode"), and listen with
(primitiv-tabs-change)="onChange($event)". There is no typing entry: Angular
types a custom element's $event as Event, so cast it to
CustomEvent<{ value: string; index: number }> in the handler.
Tooling — dist/custom-elements.json is a Custom Elements Manifest, listed
as customElements in package.json, for editor completion and Storybook.
The elements write no class and no style. For the registry look, apply the
primitiv-tabs* classes from the registry stylesheet to your markup.
Listbox
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/listbox.js"></script>
<primitiv-listbox value="apple" aria-label="Fruit">
<primitiv-listbox-option value="apple">Apple</primitiv-listbox-option>
<primitiv-listbox-option value="banana">Banana</primitiv-listbox-option>
</primitiv-listbox>- The root is the
role="listbox"and the only Tab stop: name it witharia-label. Each option element is therole="option"— there is no button to write, since an option is never focused. - A cursor instead of focus. Real focus stays on the root; the option under
the cursor is published as
aria-activedescendantand markeddata-highlighted, so style that, not:focus. The cursor lands on the first selected option (else the first) when the list takes focus, and is cleared when it loses it. The arrows, Home, End and typing move it; Enter, Space or a click chooses. valuelists the selected options, separated by spaces.type="multiple"lets options toggle independently and adds Shift+Arrow, Ctrl/Cmd+A and Ctrl/Cmd+Shift+Home/End range selection;selection-follows-focusselects as the cursor moves.primitiv-listbox-changefires first, with every option selected afterwards, and is cancelable.- Group options in
<primitiv-listbox-group>, named by a<primitiv-listbox-group-label>inside it.disabledoptions are skipped and never chosen.
Select
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/select.js"></script>
<primitiv-select name="fruit" value="apple">
<primitiv-select-trigger>
<button type="button" aria-label="Fruit"><primitiv-select-value placeholder="Pick a fruit"></primitiv-select-value></button>
</primitiv-select-trigger>
<primitiv-select-content>
<primitiv-select-item value="apple">Apple</primitiv-select-item>
<primitiv-select-item value="banana">Banana</primitiv-select-item>
</primitiv-select-content>
</primitiv-select>- The
<button>you write opens the list;<primitiv-select-content>is the list itself, arole="listbox"shown as apopover="auto"panel in the top layer and anchored to the button. Each<primitiv-select-item>is an option. Opening focuses the chosen item; the arrows, Home, End and typing move; Enter, Space or a click chooses and returns focus to the button. valueis the chosen item, mirrored into<primitiv-select-value>(an item's<primitiv-select-item-indicator>left out), which shows itsplaceholderuntil something is chosen.primitiv-select-changefires first and is cancelable;primitiv-select-open-changedoes the same foropen.- A form control with a
name. The select keeps a visually hidden native<select>inside itself — as React's Select does — so the value submits,requiredblocks an empty submit,disabledleaves it out, and a form reset restores the value it first rendered with. - A native
<select>with the registry classes needs no element at all: reach for it when the list needs nothing but text.
Combobox
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/combobox.js"></script>
<primitiv-combobox name="framework">
<primitiv-combobox-input>
<input aria-label="Framework" autocomplete="off" placeholder="Search...">
</primitiv-combobox-input>
<primitiv-combobox-content aria-label="Frameworks">
<primitiv-combobox-item value="react">React</primitiv-combobox-item>
<primitiv-combobox-item value="vue">Vue</primitiv-combobox-item>
<primitiv-combobox-empty>No matches</primitiv-combobox-empty>
</primitiv-combobox-content>
</primitiv-combobox>- The
<input>you write keeps focus throughout. It becomes therole="combobox";<primitiv-combobox-content>is arole="listbox"shown as apopover="auto"panel in the top layer, anchored to the root's child that holds the input. Typing or ArrowDown opens it; the arrows, Home and End move a virtual cursor (aria-activedescendant, anddata-highlightedon the item); Enter or a click commits; Escape or a press outside closes and puts the committed text back. Emptying the field clears the value. - Filtering is yours. Listen for
primitiv-combobox-query-change(or the input's owninputevent) and sethiddenon the items that do not match, or swap in new items from a server. Hidden anddisableditems are skipped, and<primitiv-combobox-empty>shows only while no item is. valueis the committed item; the field shows its text (itslabelattribute, else its text content).primitiv-combobox-changefires first and is cancelable, as doesprimitiv-combobox-open-changeforopen.- With a
namea hidden input inside the root submits the value — not the field's text — and a form reset restores the value it first rendered with.
Navigation Menu
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/navigation-menu.js"></script>
<primitiv-navigation-menu role="navigation" aria-label="Main">
<primitiv-navigation-menu-list>
<primitiv-navigation-menu-item value="docs">
<primitiv-navigation-menu-trigger><button type="button">Docs</button></primitiv-navigation-menu-trigger>
</primitiv-navigation-menu-item>
<primitiv-navigation-menu-item>
<primitiv-navigation-menu-link active><a href="/pricing">Pricing</a></primitiv-navigation-menu-link>
</primitiv-navigation-menu-item>
</primitiv-navigation-menu-list>
<primitiv-navigation-menu-viewport>
<primitiv-navigation-menu-content value="docs" hidden>
<primitiv-navigation-menu-link><a href="/guides">Guides</a></primitiv-navigation-menu-link>
</primitiv-navigation-menu-content>
</primitiv-navigation-menu-viewport>
</primitiv-navigation-menu>- The ARIA APG Disclosure Navigation Menu, not a menubar. Every top-level
entry stays in the Tab order; the arrows only move focus along the bar
(mirrored under
dir="rtl"), Home and End jump to its ends, the arrow across it opens a panel and focuses its first link, and Escape closes from anywhere with focus back on the trigger. Focus leaving the nav closes it too. - An item's
valuemakes it a disclosure; leave it out for a plain link entry. The<button>in its trigger toggles the panel with the samevalue— placed in its item, or in the shared<primitiv-navigation-menu-viewport>, where every panel opens in one box. Writehiddenon panels yourself. - Hover intent lives on the root:
delay-duration(200 ms) before the first open, instant swaps between siblings,close-delay(150 ms) after the pointer leaves;open-on-hover="false"makes it click-only. A click toggles against what was open when the pointer arrived, so a hover open is never undone by the click that follows it. valueon the root is the open entry (absent while closed).primitiv-navigation-menu-change(bubbles, cancelable,detail: { value },""for closed) fires before every user-driven change.- It publishes geometry, as React does: the open trigger's position and
size on
<primitiv-navigation-menu-indicator>, the open panel's size on the viewport, as--primitiv-navigation-menu-*custom properties. The styled viewport anchors to whichever trigger is open with noanchor-namein your markup.
Tree
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/tree.js"></script>
<primitiv-tree aria-label="Files" expanded="src" value="index">
<primitiv-tree-branch value="src" label="src">
<primitiv-tree-branch-control><primitiv-tree-branch-indicator>▸</primitiv-tree-branch-indicator>src</primitiv-tree-branch-control>
<primitiv-tree-branch-content>
<primitiv-tree-item value="index" label="index.ts">index.ts</primitiv-tree-item>
</primitiv-tree-branch-content>
</primitiv-tree-branch>
<primitiv-tree-item value="readme" label="README.md" disabled>README.md</primitiv-tree-item>
</primitiv-tree>- The WAI-ARIA tree view. The root is the
tree, each item and branch atreeitemwitharia-level,aria-selectedand (on a branch)aria-expanded, and a branch's content itsgroup. The rows share one tab stop; the arrows, Home and End move over the visible rows, Right expands then enters, Left collapses then climbs, and Enter or Space selects (a branch toggling too). - State is two attributes on the root, both space-separated:
expanded(the open branches) andvalue(the selection, in the order it was made).primitiv-tree-change(detail.value) andprimitiv-tree-expanded-change(detail.expanded) bubble and are cancelable. selection-mode="multiple"adds Shift ranges and Ctrl / Cmd toggles.- Write
hiddenon a collapsed branch's content yourself. The element keepshiddenandaria-hiddenin step;force-mountkeeps it rendered (onlyaria-hidden) for a stylesheet to animate. <primitiv-tree-selection-path>stamps the Breadcrumb markup in its<template>once per selected node: the first[data-tree-selection-segment]once per ancestor and the last for the node. It reads each node'slabel.
Stepper
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/stepper.js"></script>
<primitiv-stepper value="billing">
<primitiv-stepper-list label="Sign-up progress">
<primitiv-stepper-step value="account" state="complete"><button type="button">Account</button></primitiv-stepper-step>
<primitiv-stepper-step value="billing"><button type="button">Billing</button></primitiv-stepper-step>
<primitiv-stepper-step value="review" disabled><button type="button">Review</button></primitiv-stepper-step>
</primitiv-stepper-list>
<primitiv-stepper-panel value="account" hidden>…</primitiv-stepper-panel>
<primitiv-stepper-panel value="billing">…</primitiv-stepper-panel>
<primitiv-stepper-panel value="review" hidden>…</primitiv-stepper-panel>
</primitiv-stepper>- The Tabs behaviour under the stepper's own names.
<primitiv-stepper>extends the Tabs root, so the rail is atablist, each step's<button>ataband each panel atabpanel, with Tabs' keys,orientation, RTL anddisabled. It passes Tabs' own conformance suite. - Activation is
manualby default, unlike Tabs: the arrows move focus and Enter or Space changes step, so browsing the rail never discards what is half-typed in a panel.activation-mode="automatic"opts out. - A step's
state(upcoming, the default,completeorerror) is written onto its button asdata-step-state, separately from thedata-statethat marks the current step. primitiv-stepper-change(detail.value,detail.index) bubbles and is cancelable; a panel firesprimitiv-stepper-showas its step becomes current.
Miller Columns
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/miller-columns.js"></script>
<primitiv-miller-columns value="docs">
<primitiv-miller-columns-tree aria-label="Files">
<primitiv-miller-columns-column>
<primitiv-miller-columns-resize-handle aria-label="Resize column" min-width="160"></primitiv-miller-columns-resize-handle>
<primitiv-miller-columns-item value="docs">Docs<primitiv-miller-columns-item-indicator>▸</primitiv-miller-columns-item-indicator></primitiv-miller-columns-item>
<primitiv-miller-columns-item value="readme">README.md</primitiv-miller-columns-item>
</primitiv-miller-columns-column>
<primitiv-miller-columns-column parent="docs">
<primitiv-miller-columns-item value="guides">Guides</primitiv-miller-columns-item>
</primitiv-miller-columns-column>
</primitiv-miller-columns-tree>
<primitiv-miller-columns-preview-panel hidden>…</primitiv-miller-columns-preview-panel>
</primitiv-miller-columns>- Columns are siblings, not nested. Each column after the first names the
item it lists the children of with
parent; an item is a branch while some column names it. The root shows the columns on the path and setshiddenon the rest, so it never moves a node — a server can send the whole tree, only the open columns, or a column when it opens (primitiv-miller-columns-show). - The path is
value, space-separated, root first.primitiv-miller-columns-change(detail.value) bubbles and is cancelable. - The WAI-ARIA tree model on
<primitiv-miller-columns-tree>: one tab stop, the vertical arrows, Home and End within a column, the step-in arrow (Right, or Left right to left) into a branch's column and the step-out arrow back, Enter or Space to select, and typeahead within the column. <primitiv-miller-columns-resize-handle>is a window splitter (min-width,max-width,step); a resized width belongs to its depth.<primitiv-miller-columns-preview-panel>shows while the path ends on a leaf (or always, withforce-mount); its content is yours.
Table (expandable rows)
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/table.js"></script>
<table>
<tbody>
<tr>
<td>
<primitiv-table-expand-trigger>
<button type="button" aria-controls="ada-details">Show details for Ada</button>
</primitiv-table-expand-trigger>
</td>
<td>Ada</td>
</tr>
<tr id="ada-details" hidden><td colspan="2">…</td></tr>
</tbody>
</table>- The trigger sits in a cell. The HTML parser moves anything written
between a table's rows out of the table, so the button names its detail row
by id with
aria-controls, and the element writeshidden,aria-hiddenanddata-stateon that row. expandedis the state, reflected as the user toggles.primitiv-table-expand-change(detail.expanded) bubbles and is cancelable; the detail row firesprimitiv-table-expand-showas it opens.force-mountkeeps a closed row rendered (onlyaria-hidden) so a stylesheet can animate it;disabledstops the toggle.- The registry's
data-tablestyles this markup; its sorting, selection and paging stay your page's.
Code Block
<script type="module" src="https://cdn.jsdelivr.net/npm/@primitiv-ui/web@<version>/dist/cdn/code-block.js"></script>
<primitiv-code-block language="tsx" line-numbers>
<div>
<primitiv-code-block-copy>
<button type="button" aria-label="Copy code">
<span data-copy-state="idle">Copy</span><span data-copy-state="copied" hidden>Copied</span>
</button>
</primitiv-code-block-copy>
</div>
<pre><code>{{ code }}</code></pre>
</primitiv-code-block>- Write the code as text and name its
language. The element highlights it with Prism, loading Prism's core and only that language's grammars on demand — a page with no code block downloads none of it. Escape the text as any HTML text (a server template does it); the element drops the blank lines and shared indent it was pasted with, and before the script loads it reads as plain text. Prism'slanguage-*class on a<code>or<pre>works too. - Highlighted already? Left alone. Code holding Prism's token spans (from a
build step or the server) is not touched, and a page that already uses Prism
keeps its own
Prism, which the block adds grammars to. line-numberssplits the code intoprimitiv-code-block__linerows with anaria-hiddennumber each.primitiv-code-block-highlightfires after a<code>is (re)rendered.<primitiv-code-block-copy>copies its block's shown<code>(the shown panel's in a tabbed block), or the onefornames, withoutaria-hiddenparts.copiedlasts two seconds, withdata-copiedon the button, itsaria-labelswapped forcopied-label(kept indata-label), and thedata-copy-statechildren shown and hidden to match; it is transient, dropped on connect.primitiv-code-block-copy(detail.text) is cancelable.
Layers
- Controllers (
TabsController,AccordionController,CollapsibleController) hold a component's DOM behaviour — listeners, focus, the ordered collection of parts — and attach to whatever elements register with them. They never own state; their host does. - Element hosts (
<primitiv-tabs>…) are the public face: they keep state in reflected attributes and write the ARIA. The React adapter in@primitiv-ui/reactis a second host over the same controllers.
