The Theme component provides global and scoped theming for your application. It manages appearance (light/dark), border radius, roundness, spacing, and custom color tokens. Nest Theme components to create scoped overrides.
Anatomy
<Theme appearance="light">
<ThemeControl />
{children}
</Theme>Theme — Root provider that manages theme state and CSS variables.useTheme — Hook to access and modify the current theme values.ThemeControl — A floating panel (toggled with Alt+T) for adjusting theme settings at runtime.Examples
Appearance
The appearance prop controls the color scheme. Set it to "light", "dark", or "inherit" to follow the parent theme.
Light
Dark
Radius
The radius prop sets the base border radius for all child components. Options: "none", "xs", "sm", "md", "lg", "xl", "full".
Spacing
The spacing prop controls the base spacing scale used by child components. Options: "xs", "sm", "md", "lg", "xl".
Custom Colors
Use the colors prop to override theme color tokens. You can provide a flat object of colors, or separate light and dark overrides.
Nested Themes
Theme components can be nested to create scoped overrides. Child themes inherit values from their parent and only override what you specify.
useTheme Hook
The useTheme hook provides access to the current theme values and change handlers from within any child component.
Current appearance is controlled by the root Theme
import { useTheme, Button, Text } from "@locus-ui/components";
export default function ThemeToggle() {
const { appearance, onAppearanceChange } = useTheme();
return (
<>
<Text>Current: {appearance}</Text>
<Button
variant="muted"
onClick={() =>
onAppearanceChange?.(appearance === "light" ? "dark" : "light")
}
>
Toggle Theme
</Button>
</>
);
}ThemeControl
The ThemeControl component renders a floating panel with select dropdowns for all theme settings. Toggle it with Alt+T. Use the position prop to control placement.
Press Alt+T to toggle the ThemeControl panel
import { Theme, ThemeControl } from "@locus-ui/components";
import type { ReactNode } from "react";
export default function ThemeControlExample({
children,
}: {
children: ReactNode;
}) {
return (
<Theme appearance="light">
<ThemeControl position="bottom" />
{children}
</Theme>
);
}