AsheeUI
Theming

Theming

AsheeUI's theming system is CSS-variable-driven, giving you full control over colors across your entire application. It ships with two built-in themes (light and dark) plus a system option that follows the user's operating system preference.

Import

ts
import { useTheme } from "asheeui";

Built-in themes

These are the default color tokens available out of the box. Each token maps to a CSS custom property that components use internally.

TokenLightDarkDescription
background
#ffffff
#111111
Main page background
foreground
#000000
#ffffff
Primary text color
primary
#2563eb
#005bc4
Brand color / interactive elements
secondary
#ffffff
#1a1a1a
Secondary surfaces (cards, panels)
border
#d5d5d5
#2a2a2a
Borders and dividers
danger
#dc2626
#ef4444
Error / destructive actions
warning
#d97706
#f59e0b
Warning states
success
#16a34a
#22c55e
Success states
scrollbarThumb
#3b82f6
#1e40af
Scrollbar thumb color
scrollbarTracktransparent#1f293700Scrollbar track color

Setting the default theme

Define defaultTheme in asheeui.config.ts:

ts
// asheeui.config.ts
import type { ExternalConfig } from "asheeui";


export const config: ExternalConfig = {
  defaultTheme: "dark", // "light" | "dark" | "system"
  defaultVariant: "solid",
  defaultColor: "primary",
};
  • "light": Always use light theme
  • "dark": Always use dark theme
  • "system": Follow the user's OS preference (default)

Switching themes at runtime

Use the useTheme hook to read and change the current theme:

tsx
import { useTheme } from "asheeui";


function ThemeSwitcher() {
  const { theme, setTheme, toggleTheme } = useTheme();


  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme("dark")}>Dark</button>
      <button onClick={() => setTheme("light")}>Light</button>
      <button onClick={toggleTheme}>Toggle</button>
    </div>
  );
}

Return values

PropertyTypeDescription
themeThemeSelectionCurrent selected theme ("light" | "dark" | "system")
resolvedThemeThemeNameActual resolved theme (after system fallback)
setTheme(theme: ThemeSelection) => voidSet the active theme
toggleTheme() => voidCycle to the next theme in sequence
availableThemesreadonly string[]All registered theme names

Note: Theme preference persists across page reloads via localStorage.

Customizing a built-in theme

Override specific color tokens for light or dark without creating a new theme:

ts
// asheeui.config.ts
import type { ExternalConfig } from "asheeui";


export const config: ExternalConfig = {
  color: {
    light: {
      primary: "#7c3aed", // purple instead of blue
      background: "#faf5ff",
    },
    dark: {
      primary: "#8b5cf6",
      border: "#3b3b3b",
    },
  },
};

Only the tokens you specify are overridden, everything else stays at the built-in default.

Adding a custom theme

Define a new named theme that extends light or dark and overrides specific tokens:

ts
// asheeui.config.ts
import type { ExternalConfig } from "asheeui";


export const config: ExternalConfig = {
  defaultTheme: "company-red",
  color: {
    "company-red": {
      extends: "dark", // starts with dark theme values
      background: "#1a0505",
      foreground: "#fef2f2",
      primary: "#dc2626",
      secondary: "#2a0a0a",
      border: "#7f1d1d",
      danger: "#f87171",
      warning: "#fb923c",
      success: "#4ade80",
      scrollbarThumb: "#991b1b",
      scrollbarTrack: "#1a0505",
    },
  },
};

When you extend a built-in theme, you only need to specify the tokens you want to change. All others inherit from the parent.

Note: If you're using TypeScript, you need to register the custom theme name so useTheme and setTheme recognize it:

ts
// src/asheeui.d.ts or similar
import "asheeui";


declare module "asheeui" {
  interface AsheeColorRegistry {
    "company-red": true;
  }
}
Previous

← Vite

Next

Configuration →