The group's name, read by a screen reader; hidden from sight in a top bar.
initial
ThemeChoice
What the server rendered (from a cookie), before the stored choice is read. Leave it out and the control shows the operating system's theme once it mounts.
cookie
string
Where a person's choice is kept besides this browser (chooseTheme in theme-switch.ts): the site's cookie, so its server renders the next page in that theme, and the site's own save for the signed-in account. With cookie the switch starts from the server's answer.
onSave
ThemeSave
onError
(error: unknown) => void
Told when onSave throws or rejects; the choice stands either way.
ThemeButton
Prop
Type
Required
Does
prefKey
string
The localStorage key; "cap-theme" by default.
shortcut
string
The key the app binds to toggleTheme(), shown in the tip as a key cap ("T"). The app binds it.
className
string
Extra classes: the site header adds its own icon-control class.
initial
ThemeChoice
What the server rendered (from a cookie); leave it out and the label follows the page once it mounts. The icon follows the page by CSS either way.
cookie
string
onSave
ThemeSave
onError
(error: unknown) => void
Told when onSave throws or rejects; the choice stands either way.
hydrate
boolean
False on a page React never runs on in the browser: the button is written for the behavior module's enhance() to wire (its key and cookie as data-cap-pref and data-cap-cookie).
ThemeForm
Prop
Type
Required
Does
action
string
The site's theme route: a post with theme=light or theme=dark sets the cookie and comes back.
cookie
string
The cookie the press writes with script, so the server reads the same choice; "theme" by default.
className
string
Extra classes for both buttons: the site header adds its own icon-control class.
shortcut
string
The key the site binds to the theme, shown in the tips as a key cap. The site binds it.
prefKey
string
Also remember the choice under this localStorage key, for a part of the site whose shell reads it.
ThemeColor
Prop
Type
Required
Does
choice
ThemeChoice | null
The person's remembered choice (readThemeCookie), or null to follow the system.
ground
{ light: string; dark: string }
Yes
The site's --ground in each theme, as literal colors.
Functions
Function
Signature
Does
readTheme
(key?: string): ThemeChoice | null
What the person chose and the browser remembers, or null if they never did. A "system" remembered by 0.1.0 reads as no choice: the system's setting applies, as it did.
Sets data-theme, remembers the choice unless told not to, and tells every switch on the page. A person's choice (one it remembers) crossfades the page in a view transition (css/base.css), where the browser has one and motion is allowed; a restored or synced choice paints at once.
writeThemeCookie
(choice: ThemeChoice, name?: string): void
Writes the site's theme cookie from the browser, Secure on https.
A person's choice, kept everywhere the site keeps it: painted (crossfading unless animate is false), this browser's memory, the site's cookie, then the site's onSave. A save that throws or rejects goes to onError (let go without one); the page has switched and stays switched.
syncServedTheme
(key?: string): void
Where the server keeps the choice (a cookie, an account): copies the server's answer (the data-theme it wrote into the page, or none) into this browser's memory, before any switch reads it, so the two agree. With no answer the memory is cleared and the page follows the system.
applyStoredTheme
(key?: string): ThemeChoice | null
Applies the remembered choice, if there is one. Run it before first paint, or the page flashes the other theme. Returns what it applied.
effectiveTheme
(): ThemeChoice
The theme the page is painting now: data-theme when set, else the operating system's. It is right even when storage cannot be read or written, because the attribute is what applyTheme sets first.
Switches between light and dark, from whatever is showing, and keeps it as chooseTheme does (this browser, and the site's cookie and onSave when given). For a "t" shortcut.
themeButtonLabel
(showing: ThemeChoice): string
The button form says what it does, never what is showing: "Switch to dark theme" while the page is light, "Switch to light theme" while it is dark.
Attaches to every [data-cap="theme-switch"] under root. With a remembered choice, that is checked and applied. With none and a radio checked in the markup (a server that read a cookie), that one is applied. With neither, the radio for the operating system's theme is checked and nothing is applied or remembered until the person chooses, so the page keeps following the system. A change applies and remembers; the radios follow toggleTheme(), other tabs and the system. A switch with data-cap-cookie keeps the choice in that cookie too; with a cookie or an onSave it starts from the server's answer (syncServedTheme). onSave is the site's save, handed every person's choice from every switch this attaches to; onError hears a save that fails.
Parts and data attributes
Class
Is
.cap-theme
the root
.cap-theme-button
a part
.cap-theme-form
a part
.cap-theme-icon
a part
.cap-theme-options
a part
.cap-theme-text
a part
Attribute
Values
data-show
darklight
State
Read from
:checked
the platform
:disabled
the platform
:focus-visible
the platform
:hover
the platform
Accessibility
Key
Does
Tab
Moves to the checked choice
Left or Right arrow, Up or Down arrow
Checks the other choice and applies it
t
Switches light and dark, when the app registers it
A fieldset named by its legend: a screen reader hears "Theme, grouping", then "Light, radio button, checked, 1 of 2".
The checked choice is shown by the segmented control's tint and weight, not by color alone.