A theme that follows the terminal
Semantic colour roles over a static catalogue and the live terminal palette, with light and dark read from the terminal background rather than declared.
- #opentui
- #features
- #theming
Two kinds of theme have to coexist in a terminal app. One is named, shipped or written by hand, with fixed hex values. The other is the terminal's own colours, which change under the app while it runs. A component should not have to know which kind is active.
This is the provider that makes that true, on top of the terminal palette hook.
Eleven roles
Components never ask for a colour. They ask for a role:
Keeping the set small is what makes a theme quick to write and a component quick to colour. Add a role only when a component cannot express itself with the existing ones.
User-authored themes are hex-only on purpose. A named colour like "red"
resolves to whatever the terminal maps it to, which defeats the point of a
fixed theme.
A theme carries a scheme
The first version gave a theme one flat palette and an appearance: "dark" tag
beside it, which meant two separate entries for a theme that exists in both
modes. A theme now holds either shape:
"default" in scheme narrows the union in TypeScript, so a consumer cannot
read scheme.light off a mode-agnostic theme. Components read the resolved
colors from context rather than theme.colors, which is the scheme.
Light or dark is a property of the host
Nothing in a theme file says whether the environment is light. The terminal's background brightness is the only signal available, so that is where the mode comes from, including for static themes, which pick their variant from it:
Unreported or unparseable backgrounds fall back to dark, since most terminals
are dark.
Mapping the palette onto roles
The terminal theme is a pure function of one palette snapshot, with no I/O, no React and no OpenTUI import, which is what makes it testable without a renderer:
Every role ends its pick chain with a literal, because any entry the terminal
reports may be null, and the UI never receives an undefined colour.
The result is a { default } scheme rather than a pair. The snapshot already
reflects whichever mode the terminal is in, so there is only ever one palette;
when the terminal switches, the snapshot changes and this runs again.
The catalogue is an interface
The provider does not care where static themes come from. It asks three questions:
An app that loads themes from disk implements this over its loader. An app that
ships a fixed set passes catalogueFromThemes([github, nord]). The provider
does no filesystem work either way, which is what keeps it mountable in a test
with two themes and no disk.
"terminal" is reserved. A catalogue lists it and stores no colours for it;
the provider substitutes the live palette.
The terminal id never falls back to a static theme
Three separate things keep a startup from flashing the wrong colours.
The entry point pre-fetches the palette and passes it in, so the first render
already has real colours. An unresolved palette resolves to the empty-palette
terminal theme, the literal fallbacks from themeFromTerminalColors, rather
than to an unrelated named theme, so "terminal" always reads as a terminal
theme. A named id that no longer resolves, a deleted user theme for instance,
degrades to the terminal theme as well:
Changes that come from outside
A provider mounted above everything cannot subscribe to the app's own event bus, and it should not read a config file. Both directions are props instead.
onThemeChange fires when the user switches, for the caller to persist.
subscribeThemeId is its mirror. The caller pushes in an id that changed
elsewhere, either in another instance of the app or in a hand-edit of the
config. The effect only sets local state and deliberately does not fire
onThemeChange, because the value came from the persisted config and
re-persisting it is a write loop between instances.
subscribeCatalogue covers the other kind of external change: a theme file
added, edited or deleted. The caller reloads its own catalogue and then calls
the invalidate callback, and the provider re-resolves the active theme and
the picker list. Both props must be referentially stable, since they are effect
dependencies.
The pure module
The provider
Using it
The entry point owns the disk reads, which keeps them out of the React tree:
A component colours itself by role, and a terminal theme switch repaints it with no further work:
What to check when it misbehaves
A theme that reverts to its fallbacks the moment the terminal changes scheme is almost always one of the two palette-hook problems: mode 2031 never enabled, or the poll reading a cached palette. The terminal colours note covers both.
A theme that snaps back to the previous one a second after switching is the write-ordering problem. The persist is a read-modify-write, an older write landed last, and the subscribe bridge then pushed the stale id back in.
Reading theme.colors.primary instead of colors.primary is a type error
rather than a runtime surprise, which is the reason the scheme and the resolved
palette are separate fields on the context.
Related entries
- Reading the host terminal's colours. Produces the palette snapshot this maps onto roles.
Related entries
Reading the host terminal's colours
Subscribing to the terminal's own palette from React, including the DEC mode OpenTUI never enables and the cache the poll fallback has to clear.
Clipping box borders
OpenTUI's native box draw ignored the scissor stack, so a bordered box painted its border over everything around its scroll container. Fixed upstream in 0.6.0; kept for the detour it describes.
Making drag-selection opt-in
OpenTUI's text renderables are selectable by default, so a click-to-navigate UI starts a drag-selection instead. Flipping the default without disabling selection.