Applying a theme

A themed subtree needs the shared Luke UI stylesheet, one identity stylesheet, and a root carrying both theme classes. All three are static. Luke UI does not inject styles at runtime.

Import the stylesheets

Import @luke-ui/react/stylesheet.css and the stylesheet for the identity your application uses. The example below uses Tactile. Use @luke-ui/react/themes/paper.css with paperThemeClassName for Paper. Importing one bundled identity does not load the other.

Apply the root classes

Apply themeRootClassName and the matching identity class to the same element near the application root. themeRootClassName includes the reset and base theme class. The identity class supplies the semantic values.

import '@luke-ui/react/stylesheet.css';import '@luke-ui/react/themes/tactile.css';import { themeRootClassName } from '@luke-ui/react/theme';import { tactileThemeClassName } from '@luke-ui/react/themes';import { cx } from '@luke-ui/react/utils';import type { PropsWithChildren } from 'react';export function App({ children }: PropsWithChildren) {	return (		<div className={cx(themeRootClassName, tactileThemeClassName)} data-color-mode="dark">			{children}		</div>	);}

Theme identities do not nest. Use one identity for an application or independent themed subtree.

Select a colour mode

Set data-color-mode="light" or data-color-mode="dark" on the root to force a mode. Leave the attribute off to follow prefers-color-scheme.

Colour-mode scopes can nest. A child can force the opposite mode without changing the identity.

import type { PropsWithChildren } from 'react';export function DarkPageWithLightPreview({ children }: PropsWithChildren) {	return (		<div data-color-mode="dark">			Dark application			<section data-color-mode="light">{children}</section>		</div>	);}

An explicit mode also sets the native color-scheme property, so browser controls and scrollbars match the Luke UI content.

Preserve the theme in portals

Application-owned portals render outside the themed DOM branch. Give the portal root the active identity class and the explicit data-color-mode value, if there is one. If the source follows the system setting, leave the attribute off the portal root too.

Luke UI's Combobox copies this contract to its popover. Other application-owned portals need to do the same.

Avoid a colour-mode flash

Render the root classes and any known explicit mode in the server HTML. CSS can then select the correct system mode before JavaScript runs. If a stored client preference may differ from the server value, set the attribute before themed UI paints. A React effect runs after the first paint.

Keep the server fallback and hydrated value consistent to avoid a hydration warning.

Next steps

Read Authoring a theme to create a product-owned stylesheet. Use the token reference when a custom element needs public semantic values.