Theming & Customization¶

Craft Easy Admin supports light and dark themes with automatic system detection and API-driven overrides.

Theme Provider¶

Wrap your app with ThemeProvider to enable theming:

import { ThemeProvider } from '@craft-easy/admin/context';

function App() {
  return (
    <ThemeProvider>
      <AdminLayout />
    </ThemeProvider>
  );
}

useTheme Hook¶

Access theme values and mode controls from any component:

import { useTheme } from '@craft-easy/admin/context';

function MyComponent() {
  const { colors, mode, isDark, setMode } = useTheme();

  return (
    <View style={{ backgroundColor: colors.background }}>
      <Text style={{ color: colors.text }}>
        Current mode: {mode} (isDark: {isDark ? 'yes' : 'no'})
      </Text>
      <Button title="Toggle" onPress={() => setMode(isDark ? 'light' : 'dark')} />
    </View>
  );
}

Return Type¶

interface ThemeContext {
  colors: ThemeColors;           // Current color palette
  mode: ThemeMode;               // "light" | "dark" | "system"
  isDark: boolean;               // Resolved dark mode state
  setMode: (mode: ThemeMode) => void;  // Change theme mode
}

type ThemeMode = 'light' | 'dark' | 'system';

Theme Colors¶

All components use the following color tokens:

Token	Description	Light	Dark
`background`	Page background	`#f5f5f5`	`#0f172a`
`surface`	Card/panel background	`#ffffff`	`#1e293b`
`surfaceAlt`	Hover/alternative surface	`#f0f0f0`	`#273548`
`text`	Primary text	`#1a1a1a`	`#f1f5f9`
`textSecondary`	Secondary text	`#555555`	`#94a3b8`
`textMuted`	Muted/disabled text	`#999999`	`#64748b`
`primary`	Brand/action color	`#2563eb`	`#3b82f6`
`primaryText`	Text on primary bg	`#ffffff`	`#ffffff`
`border`	Border color	`#e0e0e0`	`#334155`
`error`	Error state	`#dc2626`	`#ef4444`
`success`	Success state	`#16a34a`	`#22c55e`
`warning`	Warning state	`#d97706`	`#f59e0b`
`danger`	Danger/delete	`#dc2626`	`#ef4444`
`dangerText`	Text on danger bg	`#ffffff`	`#ffffff`
`inputBackground`	Input field bg	`#ffffff`	`#1e293b`
`cardBackground`	Card bg	`#ffffff`	`#1e293b`

Theme Mode Logic¶

Mode	Behavior
`system`	Follows device preference via `useColorScheme()`
`light`	Forces light theme regardless of system setting
`dark`	Forces dark theme regardless of system setting

The isDark value is computed as:

const isDark = mode === 'system' ? systemScheme === 'dark' : mode === 'dark';

API-Driven Theme Override¶

The API can customize the admin theme via the schema's theme property:

{
  "theme": {
    "primary_color": "#10b981",
    "logo_url": "https://example.com/logo.png",
    "favicon_url": "https://example.com/favicon.ico"
  }
}

When a session schema includes theme.primary_color, the admin app overrides the default primary color token. The logo_url and favicon_url are used in the sidebar and browser tab respectively.

Theme Toggle¶

The header includes a built-in theme toggle button that cycles through modes:

system → light → dark → system → ...

The button displays the current mode label ("Light" / "Dark") and updates immediately.