API
Global attributes
The data-ui-* attributes no primitive owns.
Everything a primitive owns is data-<primitive>-*. Four attributes belong to the page instead and keep the data-ui- prefix.
| Attribute | Values | What it does |
|---|---|---|
data-ui-navigation | swap | On <html>: swap the body in place on navigations between opted-in pages. |
data-ui-persist | free value | Keep this element's live DOM, state and scroll offsets across in-page navigations; its links take aria-current from the next page. The value is an id both pages share. |
data-ui-persist-scroll | free value | Render this element from the next page but keep its scroll offset across in-page navigations (a section sidebar, a table of contents). The value is an id both pages share. |
data-ui-guard | off | Opts an element out of the style guard. |
Theme
The theme-dark and theme-light switches are data-ui tokens (data-ui="theme-dark"), listed with the other switches. On any element one pins that scheme for the subtree; it only sets color-scheme, so scopes nest and every light-dark() token follows. Without one, the page follows the system. The head's theme script adds the switch to <html> from localStorage.theme before first paint.
Navigation and persistence
With data-ui-navigation="swap" on <html>, a same-origin navigation between two opted-in pages fetches the destination and swaps the whole <body> in place. Nothing survives the swap unless it carries data-ui-persist="<id>" on both pages; then the live element moves into the new page with its state and scroll offsets, and its links take aria-current from the new page. data-ui-persist-scroll="<id>" renders an element from the new page but keeps its scroll offset, for a region whose content changes per page, such as a sidebar. Reloads, hash changes, downloads, and form posts are never intercepted. See navigation.
Style guard
data-ui-guard="off" opts an element out of the style guard, which otherwise restores style utilities a legacy script overwrites.