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.

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  <Theme appearance="light" radius="md" spacing="md">
    <Box className="flex gap-2 items-center">
      <Button variant="solid">Themed Button</Button>
    </Box>
  </Theme>
</Flex>

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

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  <Box className="flex gap-4">
    <Theme appearance="light">
      <Box className="p-4 rounded bg-[rgb(var(--bg-1))]">
        <Text>Light</Text>
      </Box>
    </Theme>
    <Theme appearance="dark">
      <Box className="p-4 rounded bg-[rgb(var(--bg-1))]">
        <Text>Dark</Text>
      </Box>
    </Theme>
  </Box>
</Flex>

Radius

The radius prop sets the base border radius for all child components. Options: "none", "xs", "sm", "md", "lg", "xl", "full".

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  {["none", "xs", "sm", "md", "lg", "xl", "full"].map((radius) => (
    <Theme key={radius} radius={radius}>
      <Button variant="solid">{radius.toUpperCase()}</Button>
    </Theme>
  ))}
</Flex>

Spacing

The spacing prop controls the base spacing scale used by child components. Options: "xs", "sm", "md", "lg", "xl".

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  {["xs", "sm", "md", "lg", "xl"].map((spacing) => (
    <Theme key={spacing} spacing={spacing}>
      <Button variant="solid">{spacing.toUpperCase()}</Button>
    </Theme>
  ))}
</Flex>

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.

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  <Theme colors={{ primary: "teal" }}>
    <Button variant="solid">Custom Primary</Button>
  </Theme>
</Flex>

Nested Themes

Theme components can be nested to create scoped overrides. Child themes inherit values from their parent and only override what you specify.

<Flex gap="4" wrap="wrap" align="center" justify="center" className="w-full">
  <Theme appearance="light" radius="md">
    <Box className="flex gap-2 items-center">
      <Button variant="solid">Parent Theme</Button>
      <Theme appearance="dark" radius="full">
        <Button variant="solid">Sub Theme</Button>
      </Theme>
    </Box>
  </Theme>
</Flex>

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

<Flex
  gap="4"
  wrap="wrap"
  align="center"
  justify="center"
  className="w-full"
  direction="column"
>
  <Text>Current appearance is controlled by the root Theme</Text>
</Flex>
Implementation
Code
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

<Flex
  gap="4"
  wrap="wrap"
  align="center"
  justify="center"
  className="w-full"
  direction="column"
>
  <Text>Press Alt+T to toggle the ThemeControl panel</Text>
</Flex>
Implementation
Code
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>
  );
}