Building with TUI

When to read this: Use when writing, reviewing or testing React UI that imports @tangible/ui (TUI) — components render unstyled or unthemed, a portalled Modal/Select/Popover loses its tokens or its theme, dark mode does not follow the host app, a prop or type will not resolve, a label or error is not announced, or you need to know which component (or token) to reach for.

Consumer-side skill: how to build an app with @tangible/ui. (Building TUI itself is covered by the repo's own CLAUDE.md and .claude/agents/*.)

The API is on disk and does not need guessing. What costs hours is the wiring and the a11y plumbing, because both fail silently rather than erroring. That is most of what follows.

Inventory figures (component counts, manifest coverage, subpaths, icons, data-testid pass-through) were re-measured against 0.2.28 (Oct 13 2026). Other sections were last verified against 0.2.11 + main (Aug 22 2026) unless a claim carries its own date. Re-check anything that reads as surprising.

The minimum that works

import '@tangible/ui/styles';            // once, app-wide — Wiring §4 picks the right entry
import { Button } from '@tangible/ui';

<div className="tui-interface" data-theme="dark">   {/* omit data-theme for light */}
  <Button label="Save" theme="primary" />
</div>

Both halves are load-bearing. Without .tui-interface there are no tokens; without the stylesheet there is no CSS at all.

Where the API lives

The docs are also fetchable as plain markdown, no JS needed: https://storybook-tangible-ui.pages.dev/llms.txt indexes every guide and one page per component (props, defaults, API tokens); llms-full.txt is all of it in one file. Prefer it over the Storybook UI when you can only fetch URLs.

node_modules/@tangible/ui/ — read in this order, stop when answered:

Directory and file name match, with two exceptions: Table/DataTable.d.ts and ColorPicker/ColorField.d.ts. Props live in types.d.ts for 35 of 46 components; the other eleven declare them in the component file (Card, Chip, Chips, ColorPicker, Field, GradientPicker, Icon, Modal, Notice, OverlapStack, Toast). <Dir>.d.ts is still the better read for the compound shape — it spells out type SelectCompound = … & { Trigger; Content; Option; Group; Label } in one place, which the barrel's flat export list only implies.

Do not use tui-manifest.json for props. It is curated for narrative, not completeness, and the filter drops load-bearing API:

• It keeps exactly five on* props — onClick, onChange, onClose, onDismiss, onValueChange — and drops every other callback. onCheckedChange, onOpenChange, onInputChange, onSearch, onClear, onRemove, onPageIndexChange, onSelectionChange are all absent.
• Any prop without a JSDoc comment is dropped, required or not. The clearest tell: the manifest's Checkbox entry lists rel and title but not checked, defaultChecked, indeterminate or onCheckedChange — the entire state API is missing while inherited HTML noise survives.
• 39 components report subcomponents: null, and for 13 of those the compound API is real (Select, MultiSelect, SearchSelect, Combobox, MultiCombobox, Dropdown, Popover, Tooltip, Field, Sidebar, StepList, Toolbar, NavMenu) — #87.
• Only 8 of 46 entries carry a description, and 4 carry use/notFor, so it is a thin guide to which component too. The two guides entries (Tabs vs SegmentedControl, Chip vs Button) are worth reading; the rest of that judgement is not in the file.

Manifest silence is not absence. What it is good for: cssTokens (43 of 46 components list their full --tui-<component>-* API — the only shipped listing, since consumers have no SCSS) and story (all 46, pointing into https://storybook-tangible-ui.pages.dev).

Types that will not resolve from the barrel

@tangible/ui re-exports the main *Props types but systematically omits others. Import those from @tangible/ui/components/<Dir> — all 46 component subpaths are exported.

• Nearly every *Labels type (the i18n prop): ButtonLabels, FieldLabels, ComboboxLabels, MultiSelectLabels, RatingLabels, DataTableLabels, AvatarLabels, StepIndicatorLabels, CalendarLabels, … (PagerLabels is the exception — exported since 0.2.12.)
• Most union / variant aliases: AccordionVariant, ContentIndicatorSize, ComboboxFilterMode, IconButton's Shape/Variant, NoticeHandle, ProgressSegment, OptionValue, TooltipTheme, … (SidebarFooterProps was on this list until 0.2.18, which also exported the new SidebarToggleProps.)
• All of DatePicker — the barrel exports zero DatePicker types: DatePickerProps, DateRangePickerProps, CalendarProps, DateRange, DateRangePreset, WeekStart.
• SliderProps, which is missing entirely.

Also: @tanstack/react-table is a real dependency of TUI, not a peer, so it installs automatically — but under pnpm it has no root symlink, so ColumnDef will not resolve from app code. Use DataTableProps<T>['columns'] instead.

Naming conventions — so you don't guess

Clearing a clearable control calls back with undefined, not ''. Controlled-vs-uncontrolled is locked at mount, so a value that becomes undefined does not silently flip the component to uncontrolled — but your own state has to tolerate undefined.

Buttons take either label (simple text) or children (rich content).

Wiring (each of these fails silently)

1. .tui-interface is mandatory. Every token is defined in one :where(.tui-interface){…} block. Without that ancestor, components render with no design tokens at all.

2. Portalled UI resolves its host from the trigger. Modal, Select, Dropdown, Popover and Tooltip portal via getPortalRootFor(trigger), which walks up from the trigger to the nearest .tui-interface and appends a portal root there. So a trigger inside your wrapper needs nothing. The failure case is a trigger that has no .tui-interface ancestor: TUI then creates its own body-level wrapper and snapshots data-theme from <html>/<body> once, at creation. It never re-reads it, so a host that toggles theme after mount gets stale portalled content. Wrapping your JSX does not fix a Modal rendered outside the tree — the dialog is not in that subtree.

Only Modal takes a container prop. If you need to place it yourself, create a body-level .tui-interface div, keep data-theme live on it, and pass it as container — attaching in a useLayoutEffect, because Modal resolves its container in a layout effect and focusing a detached node silently does nothing. For the rest of the family, the fix is to put the trigger inside a .tui-interface. getPortalRootFor is importable from @tangible/ui/utils/portal if you need to resolve the same root yourself.

If <html> itself is the .tui-interface, portal roots mount inside <body>, not on <html>.

3. Dark mode is data-theme, not a class. TUI's palette is gated on [data-theme="dark"] ("auto" follows prefers-color-scheme; absent means light and inherits the host's colour). With data-theme="dark"/"auto" on an ancestor such as <html> and an un-themed .tui-interface on <body>, TUI surfaces (panels, cards, filled controls) render correctly because they own their text colour, but in-flow text directly inside the interface still inherits the HOST's colour by design — so set the host's own body colour (e.g. color: var(--tui-color-fg) on body) if you want TUI's. A host that toggles a .dark class (Tailwind's strategy) drives nothing in TUI. Translate it: observe what is actually applied to the document — a MutationObserver on <html>'s class catches boot, explicit toggles and OS changes alike — and mirror it onto your wrapper. Resolve to explicit light/dark rather than TUI's auto, or an explicit light choice on a dark OS will be wrong.

4. Pick the stylesheet by host.

• Host with its own CSS layers (Tailwind v4, or any @layer author): @tangible/ui/styles/unlayered. TUI declares @layer resets, defaults, components, utilities — components and utilities collide with Tailwind's own names, layers merge across stylesheets, so bundle order would decide cascade order for both. If TUI won that race, the host's preflight would sort after its own utilities and start overriding them app-wide.
• WordPress / unlayered theme CSS: @tangible/ui/styles/unlayered too — layered CSS loses to unlayered theme styles.
• Otherwise the default @tangible/ui/styles.

Consequence of unlayered: inside .tui-interface, TUI beats host utility classes. Style TUI elements with --tui-* tokens and TUI utilities only — a host utility class there silently loses.

5. Import the stylesheet once, app-wide (entry or global CSS), not per component: all.css is ~270 kB raw / ~30 kB gzipped and lands in whichever chunk first reaches a component. Two ways down if that matters: @tangible/ui/styles/core (~44 kB — tokens, resets, utilities, icon, no components), or, if your build compiles Sass, the documented subset entry:

@use "@tangible/ui/styles/index" with (
  $components: (button, checkbox, radio, notice, modal),
  $layers: false
);

Labels and errors: Field composition

Field wires id / aria-labelledby / aria-describedby / aria-invalid / aria-required onto its control by cloning it. Get the composition wrong and the control loses its accessible name or its error — visually identical either way.

<Field error={!!err} required>
  <Field.Label>Course</Field.Label>      {/* MUST precede Field.Control */}
  <Field.Control><Select …>…</Select></Field.Control>
  <Field.HelperText>Pick one</Field.HelperText>
  <Field.Error>{err}</Field.Error>
</Field>

Three rules, all of them silent when broken:

• Field.Label before Field.Control in JSX. aria-labelledby is injected only when a label has already rendered — a phantom aria-labelledby would resolve to the empty string and strip all other name sources (AccName 1.2 step 2B), so TUI withholds it rather than risk that. A dev warning fires on the wrong order; production is just unlabelled.
• Self-labelling controls omit Field.Label entirely. Checkbox and Switch with their own label prop already have a name; adding Field.Label makes AT concatenate both.
• Group controls need Field.Label as="span". RadioGroup and SegmentedControl render role="radiogroup" on a <div>, which is not a labelable element, so the default <label for> dangles. The span keeps the id, so the aria-labelledby wiring is untouched.

Not every control accepts every injected attribute. aria-required is role-gated: the triggers that are plain <button aria-haspopup="dialog"> (SearchSelect, DatePicker, DateRangePicker) resolve to role="button", which does not allow it — axe flags aria-allowed-attr. TUI deliberately does not declare it there; the requirement still reaches AT through Field.Label's visually-hidden "required" text. If axe reports aria-allowed-attr on a TUI trigger, it is TUI's to fix, not yours (ColorField currently passes it through — verified Aug 22 2026, not yet filed).

Customising

Tokens, not class overrides. Four layers, and you only touch two:

/* Primitives — the theme contract. Set on .tui-interface or any ancestor. */
.tui-interface { --tui-radius-md: 2px; --tui-focus-ring-color: hotpink; }

/* Component API — never defined by TUI, only read. Set anywhere that wins. */
.compact-form { --tui-select-trigger-radius: 2px; --tui-accordion-padding: 8px; }

--_* is component-private and $_* compiles away; neither is yours to set. Names come from tui-manifest.json → cssTokens.

Every layer-1 primitive — colour roles and the scale (spacing, radius, type sizes, weights, shadows) — is emitted at :where(.tui-interface), specificity (0,0,0). A site theme written at :where() after TUI's sheet therefore overrides all of them uniformly; before 0.2.21 the scale block sat at bare .tui-interface and such a theme won the colours but silently lost the layout tokens.

Colour maths ships as public utils: @tangible/ui/utils/color (parseColor, formatColor, rgbToOklch/oklchToRgb, rgbToHsl, hexToRgba, …), @tangible/ui/utils/color/gradient (parseGradient/formatGradient), and @tangible/ui/utils/color/contrast (getContrastTone, getContrastForeground, contrastRatio(hexA, hexB) — WCAG ratio 1–21, NaN on bad input so a >= 4.5 check fails closed). Use them for user-selected colours and theme tooling (deriving or validating a ladder), not to pick a component's own theming at runtime.

Useful primitives:

• Surfaces / text: --tui-color-bg, -bg-surface, -bg-elevated, -bg-muted, -bg-inverted, --tui-color-fg, -fg-secondary, -fg-muted, -fg-on-accent, --tui-color-border, --tui-color-border-control (form-control boundaries, 3:1; --tui-color-border is decorative), --tui-color-divider, --tui-color-fill{,-subtle,-strong}, --tui-color-focus-ring.
• Themes: --tui-theme-{primary,secondary,success,warning,danger,info}-{subtlest,subtle,soft,base,strong,stronger,strongest}. The ladder is contrast-based — "stronger" always means more contrast against the current background, so a single choice reads correctly in both light and dark mode.
• Control heights, shared by every form control and Button / IconButton / SegmentedControl / Pager: --tui-control-height-{sm,md,lg} (32 / 40 / 48px, plus an xs at 24px that only Button / IconButton / SegmentedControl offer — there is no xs form-control tier). Add --tui-control-font-size-{sm,md,lg} to decouple type size from the height tier. One override normalises a whole host context at once.

Two families share a token layer, so you can restyle the whole family in one place:

• Control chrome: --tui-input-{bg,fg,border,border-focus,border-hover,radius} reaches TextInput, SearchInput, the pickers and every select-family trigger.
• Listbox panels and options (Select, MultiSelect, Combobox, MultiCombobox, SearchSelect; 0.2.23+):
  • Panel: --tui-listbox-{bg,fg,border,shadow,radius}.
  • Options: --tui-listbox-option-{radius,gap,bg-hover,fg-hover,bg-selected,fg-selected,bg-selected-hover,check}.

Form controls show no border change on hover unless you set --tui-input-border-hover (opt-in; focus, open and invalid still win). A component's own token (e.g. --tui-combobox-option-bg-selected) overrides the shared one for that component only. If you re-point an option state's background, set its -fg-* partner too: the text defaults to the panel's own fg, which is tuned for TUI's default fills.

Text styles (0.2.24+) are classes: .tui-text-style-{display-01…04, headline-01…06, body, body-sm, label, caption, overline}. Restyle a treatment everywhere through its one class (.tui-text-style-overline { text-transform: none } reaches every listbox group label and the Dropdown header), or through its knobs, --tui-text-{style}-{family,size,weight,line-height,tracking,transform,color}. Knobs are never declared, so :root works. --tui-text-headline-weight retunes every headline level at once.

Fonts: TUI inherits the host's font. If your page has none (you see the browser's serif), add tui-font-sans next to tui-interface, or set --tui-font-family-base anywhere. --tui-font-family-sans / -mono replace the stacks those utilities use.

Tooltips warm up in groups: wrap a set of tooltips in TooltipProvider (a Toolbar does it for you), and after the first shows, the rest appear at once while you move between them (skipDelayDuration, default 300ms). Don't hand-roll delay logic per tooltip.

className is for layout integration (margin, grid placement), not appearance. Beyond the token API the sanctioned escape hatch is to swizzle — copy the component source and own the fork.

Styling one member of a group

Selection components expose their state as attributes, so you can style a particular option without threading a className through every item. SegmentedControl.Item, Tabs.Tab and Radio carry data-value (the item's own value) and data-state (active / inactive), plus data-disabled when disabled; data-state is the same vocabulary Accordion, Modal, Sidebar and DataTable already use.

/* Grading control: failing red, passing green — only when chosen. */
.tui-segmented__item[data-value='fail'] {
  --tui-segmented-item-bg-active: var(--tui-theme-danger-subtlest);
  --tui-segmented-item-fg-active: var(--tui-theme-danger-stronger);
}
.tui-segmented__item[data-value='pass'] {
  --tui-segmented-item-bg-active: var(--tui-theme-success-subtlest);
  --tui-segmented-item-fg-active: var(--tui-theme-success-stronger);
}

On SegmentedControl's outline variant the selected border is the whole selection indicator, and it has its own token — --tui-segmented-item-border-active (added 0.2.17). Before that it read the theme token directly, so the fill and text were overridable per value and the border was not. If you recolour a segment in the outline variant, move the border with the fill or the option will read as the wrong colour outlined in the theme's:

.tui-segmented__item[data-value='fail'] {
  --tui-segmented-item-bg-active: var(--tui-theme-danger-subtlest);
  --tui-segmented-item-fg-active: var(--tui-theme-danger-stronger);
  --tui-segmented-item-border-active: var(--tui-theme-danger-base);
}

Check the border you pick against the page, not against the fill — it is a non-text indicator, so WCAG SC 1.4.11 asks for 3:1 there, and a tone that looks right on the fill can fall under that against a dark page. TUI's own defaults are 3.60:1 (dark) and 7.52:1 (light).

Reach for the component's own tokens inside the rule, as above, rather than setting background directly — that keeps the hover and focus treatments the component already derives. Note that --tui-segmented-item-bg-active only applies when the item is active, so the selector above does not need [data-state='active'] as well; add it when the property you are setting is not already state-scoped. Token names come from tui-manifest.json → cssTokens.

Recolour the foreground with the background. The pairing above is -subtlest fill with -stronger text — the two-sided pairing Chip already uses, and both halves move with the theme. Setting only the fill to a -base tone leaves the default white-on-accent foreground behind, which clears 4.5:1 in light mode and then fails it in dark, because the dark ladder lightens: danger drops to 3.7:1 and success to 3.4:1. The ladder cannot rescue this on its own — "stronger" means more contrast against the page, so in dark mode it moves the fill towards the text, not away from it.

All three items accept aria-label and aria-labelledby as declared props, so naming one from visible text elsewhere is supported — but aria-labelledby replaces the item's own label rather than adding to it, and an id that matches nothing empties the name completely. Point it at an element that exists, and check the name you actually get.

Radio puts these on the wrapper <div class="tui-radio">, so a rule can reach the label and description too. Tabs.Tab also carries data-tui-tab-value; that one is internal (Tabs reads it back for focus lookup) — style against data-value.

Replacing a trigger with asChild

Select.Trigger, Dropdown.Trigger, Popover.Trigger, Tooltip.Trigger, Accordion.Trigger, MultiSelect.Trigger, DatePicker.Trigger and DateRangePicker.Trigger all take asChild, rendering your element in place of theirs.

The two pickers render their trigger automatically when the root has no children, so <DatePicker /> is unchanged. Reach for DatePicker.Trigger when you want to place the trigger yourself — which is what lets the whole popover (time field, Now, month/day/year, calendar) hang off a text field the user can also type into freely:

<DatePicker withTime onChange={(date) => setText(format(date))}>
  <TextInput
    value={text}
    onChange={(e) => setText(e.target.value)}
    suffix={
      <DatePicker.Trigger asChild>
        <IconButton icon="lms/calendar" label="Pick a date" variant="ghost" size="sm" />
      </DatePicker.Trigger>
    }
  />
</DatePicker>

TUI never writes into the field: onChange hands you a Date and you decide what string goes in, which is why this works with formats TUI knows nothing about ("3pm ET" survives being typed). Children with no Trigger among them leave the picker unopenable — a dev warning fires.

Size a slot button one tier below the field (md field → sm button). Button and IconButton anchor to --tui-control-height-*, which is the whole field's height; TUI cancels the group's padding so it no longer inflates the field, but a same-tier button still fills the content box edge to edge.

Four things change versus a picker's default trigger, all deliberate:

• Your element owns its accessible name, so name it for the action ("Pick a date"). The default trigger appends its value text to the name; asChild cannot, because there is no value span — and a dangling aria-labelledby id would resolve the entire name to empty.

• No tui-input-group chrome is applied. That is the point (a bare button, not a bordered field) and it is where the pickers diverge from Select.Trigger, which force-applies the class even under asChild. It also means aria-invalid still lands on your element but paints nothing, so an invalid trigger inside a Field needs one rule of your own:

  .my-date-trigger[aria-invalid='true'] {
    border-color: var(--tui-theme-danger-base);
    color: var(--tui-theme-danger-base);
  }
  

  Everything else Field injects works unchanged — Field.Label reaches the accessible name, and Field.Error is announced via aria-describedby.

• disabled arrives as aria-disabled + data-disabled, since your element may not be a <button>. The popover refuses to open either way, in the open direction only — closing is never blocked, so disabling a form mid-submit cannot strand an open popover.

• Your element must be natively focusable and keyboard-activatable — a <button> or <a>, not a styled <div>. No key handler is attached under asChild; it relies on the child turning Enter/Space into a click, which only real interactive elements do.

Your child's onClick still runs; call preventDefault() in it to suppress the toggle.

Accordion.Trigger asChild is the one that paints. By default it stamps tui-accordion__trigger on your element — the full-width row look (flex, width: 100%, padding, hover background, inset focus ring), which is what a custom header row wants. If your child is already a styled control (an IconButton chevron in a repeater row), pass unstyled so it keeps its own sizing and focus ring; data-tui-accordion-trigger and data-state still land, so you can style off the behaviour without the paint. A native <button> child activates on Enter/Space through the browser, once — TUI does not synthesise a second toggle. For a second control that toggles the same item (an Edit/Close link), useAccordionItem() returns { isOpen, panelId, toggle, … } for its own aria-expanded/ aria-controls. Controlled single-mode accordions take value={null} for "nothing open" — undefined would flip them uncontrolled.

Component names, and what isn't there

46 components. If you are hunting for a name: Alert → Notice, Menu → Dropdown, Table → DataTable, Pagination → Pager, Drawer → Sidebar (drawer mode), Nav menu / sidebar links / top nav bar → NavMenu (inside Sidebar.Nav or your <nav>; asChild for router links, current for aria-current; orientation="horizontal" for a bar whose items open flyouts, flyoutTrigger="hover" to also open on mouse hover; suffix for a row badge/count — a Chip, with visually hidden context for bare numbers, never interactive; row states restyle via --tui-nav-menu-item-*, per level via --tui-nav-menu-{sub,bar,flyout}-item-* — set bar-item-* for a dark header so flyout rows keep the panel's colours; don't hand-roll menus with role="menu"), Badge → Chip or ContentIndicator, Spinner → Progress or Button loading, ConfirmDialog / AlertDialog → Modal role="alertdialog" (needs both aria-labelledby and aria-describedby; the backdrop stops dismissing by default, Escape still cancels; put the actions in Modal.Foot, which is already an end-aligned flex row — justify="between" separates a destructive one). Snackbar → Toast (ToastProvider + useToast()). Password / API key / token field → SecretInput (a TextInput variant: masked, with a reveal toggle whose name flips Show/Hide; isSet is a boolean so a stored secret never reaches the client, it shows a "Saved" placeholder and typing replaces it; locked makes it read-only with no toggle). No Breadcrumb, no Skeleton, and no standalone time picker — but DatePicker / DateRangePicker take withTime for an hour/minute field (12- or 24-hour via hour12) plus a display-only zoneLabel; the value is a plain Date with wall-clock semantics, so timezone interpretation stays yours.

Two clusters are easy to pick wrong:

• Chip family — Chip is one chip. ChipGroup is a selectable set with radio/checkbox semantics (value / onValueChange / multiple). Chips is a display list rendered from a ChipOption[] array, with link support and no selection.
• Select family — Select (single, not typeable), Combobox (single, the input is the trigger, you own the filtering via inputValue/onInputChange), SearchSelect (single, a button trigger with the search field inside the panel), MultiSelect (multi, button trigger, count or chips in the trigger), MultiCombobox (multi, free-typing token field). All five share one listbox engine, so navigation and ARIA behave identically; the trigger is the choice.

Icons are a registry, six sets, 255 entries (Oct 13 2026): system (116), lms (45), reaction (36), player (24), membersync (22), cred (12). @tangible/ui/icons/manifest is the machine-readable list.

<Icon name="system/check" />                {/* decorative — hidden from AT automatically */}
<Icon name="system/lock" label="Locked" />  {/* informative — label makes it announced */}

There are no device icons (monitor / tablet / phone) in any set.

Testing hooks

data-testid pass-through is uneven, and the split is not the one you would guess. These spread rest props onto their primary element: Button, Card, Checkbox, Chip, ColorPicker, ColorField, Field's slots, GradientPicker, IconButton, Modal, NavMenu (root, .Group, .Sub, .Item), Notice, SearchInput, SearchSelect, SecretInput, Switch, Textarea, TextInput, Toast, DataTable (onto the <table>), and — since 0.2.16 — the group members SegmentedControl.Item, Tabs.Tab and Radio. Everything else drops them silently, including several that look like they would take them — Dropdown, Popover, Tooltip, Select, MultiSelect, Combobox, MultiCombobox, Sidebar, Toolbar, Pager, Rating, Progress, Avatar, Icon, Slider, MoveHandle, StepList, DatePicker.

Two notes on those three. Radio spreads onto the wrapper <div class="tui-radio">, not the control its ref targets — the wrapper is where className already goes, and it is the element holding the label and description. And on all three the spread is applied before the component's own attributes, so a forwarded role or aria-checked cannot desynchronise the group from what it announces; the props types omit those, so TypeScript rejects them rather than dropping them.

Typecheck will not save you here: TypeScript exempts hyphenated JSX attributes from excess property checking, so <Select data-testid="x" /> compiles clean against a prop type that has no such prop and then never reaches the DOM. (Same mechanism makes aria-hidden on <Icon> a silent no-op — Icon neither declares nor spreads it. Icons are decorative by default; that is what the missing label already means.) A misspelled non-hyphenated prop does error, and IconName is a literal union, so <Icon name="system/typo" /> fails the build.

The check, since that list will drift: grep the component's built file in node_modules/@tangible/ui/components/<Dir>/ for ...rest. If it isn't there, target the stable class (tui-select__trigger) or the ARIA role instead.

DataTable rows are the exception worth knowing: per-row props go through getRowProps(row) — data-testid, refs, tabIndex, handlers — and it composes with controlled pagination (pageIndex / onPageIndexChange, 0-based).

One live trap there: memoize data, or pass autoResetPageIndex={false}. A derived array gets a new identity every render, TanStack queues a page-0 reset on every data identity change, and with a controlled pageIndex that races your parent back to page 0 permanently.

Vanilla modal (no React)

For templates and plugin PHP with no React build (Tangible Blocks, L&L): @tangible/ui ships a framework-free modal on the native <dialog>. It replaces MicroModal; there is no compat layer, so the markup differs.

<link rel="stylesheet" href="https://unpkg.com/@tangible/ui/vanilla/styles.css"> <!-- or all.css, not both -->
<script src="https://unpkg.com/@tangible/ui/vanilla/modal.min.js" defer></script>

<button type="button" data-tui-modal-open="intro">Watch</button>

<dialog id="intro" class="tui-interface tui-modal" aria-labelledby="intro-title">
  <div class="tui-modal__dialog is-size-lg">  <!-- required: a click on the <dialog> itself is the backdrop -->
    <div class="tui-modal__head"><h2 id="intro-title">Intro</h2></div>
    <div class="tui-modal__body"><div class="tui-modal__body-inner">
      <iframe class="tui-modal__embed" title="Intro video" data-tui-modal-src="https://www.youtube.com/embed/ID?autoplay=1"></iframe>
    </div></div>
    <div class="tui-modal__foot">
      <button type="button" class="tui-button" data-tui-modal-close>Close</button>
    </div>
  </div>
</dialog>

• Attributes. data-tui-modal-open="<id>" and data-tui-modal-close go on any element (delegated, so markup added later works; aria-disabled triggers are ignored). On the dialog, role="alertdialog" (add aria-describedby) and data-tui-modal-backdrop="dismiss" | "static"; alertdialog defaults to static. [autofocus] / [data-autofocus] picks initial focus. A submit button or link carrying data-tui-modal-close keeps its default action. data-tui-modal-restore-focus="<id>" on the dialog names where focus goes on close, for when the opener is gone (a Delete-row confirm); otherwise it returns to the opener. Put .tui-modal__close last in the box: initial focus skips it unless it's the only control.
• State and events. The script sets data-state to open, closing or closed. tui-modal-open and tui-modal-close bubble from the dialog; close's detail.returnValue is the submitting button's value in a <form method="dialog">. window.TangibleUI.modal exposes open(idOrDialog) and close(...).
• Embeds. data-tui-modal-src loads on open and is dropped on close, which stops a YouTube or Vimeo player with no postMessage script. <audio>/<video> pause. Always give the iframe a title.
• Name it. The dialog needs aria-labelledby pointing at an element that exists (a phantom id leaves it unnamed) or an aria-label, and an icon-only close needs its own aria-label (the script can't see that one). The script warns in the console about a missing or phantom name, a dangling aria-describedby, an alertdialog without aria-describedby, a missing .tui-modal__dialog box and no close control; warnings are always on.
• Two enqueues are fine. If Blocks and L&L both load the script, only the first copy installs.
• Limit: the top layer. A native modal puts everything else inert and renders above it. A React Select, datepicker or any widget portaled to <body> renders under the dialog and can't be used inside it. Keep such controls in the dialog's own markup.

Known issues

Each is tracked in the repo, so follow the link for current state rather than trusting this list — an issue closes on its own, a bullet here does not. This section used to enumerate bugs inline and went stale within a week; one of its entries turned out never to reproduce at all. Re-verify before you work around anything.

• DateRangePicker cannot express an open-ended range — Apply is inert unless both endpoints are set, so "starts now, no end date" is unreachable. (#86)
• tui-manifest.json is lossy — see "Where the API lives" above for the shape of it. (#87)

Verify

tsc --noEmit catches guessed props immediately — TUI ships types, and most unions are literal. It cannot see any of the wiring above.

What typecheck misses, in the order it bites:

1. Open a portalled component (Modal or Select) in dark mode. That single check exercises the portal host, the theme bridge and the token scope at once — it is where all three break.
2. Tab to each control and confirm the accessible name and the error text are announced (the Field rules above). A browser a11y inspector or axe is enough; both failures are invisible.
3. Narrow the layout. Card, Notice and Pager respond to their container, not the viewport, so shrinking the window proves nothing if they sit in a fixed-width parent — resize the parent instead.

Reference consumers

tangible-autism-certify (graded A — the reference), tangible-cron-manager-pro, tangible-datastream, tangible-searchsync — all WordPress plugins on roller with react: 'wp' (React 18). tangible-app is the first React 19 consumer, so React 19 incompatibilities surface there first. Read one before inventing a pattern.