Theme Customization Guide

ThemeContext exposes all 25+ customisation dimensions through useThemeContext(). Changes are persisted to localStorage automatically.

Reading and writing theme settings

import { useThemeContext } from "@xocialive/ui-components/contexts";

function ThemeSwitcher() {
  const {
    mode,
    setMode,
    colorTheme,
    setColorTheme,
    fontFamily,
    setFontFamily,
    fontSize,
    setFontSize,
    borderRadius,
    setBorderRadius,
    scrollbarStyle,
    setScrollbarStyle,
  } = useThemeContext();

  return (
    <>
      <Switch checked={mode === "dark"} onChange={(e) => setMode(e.target.checked ? "dark" : "light")} />
      <Select value={colorTheme} onChange={(e) => setColorTheme(e.target.value)}>
        <MenuItem value="aurora">Aurora</MenuItem>
        <MenuItem value="ocean">Ocean</MenuItem>
      </Select>
    </>
  );
}

Customization dimensions reference

Dimension	Setter	Type
Colour mode	setMode	"light" | "dark"
Colour palette	setColorTheme	ThemePaletteName (9 options)
Font size	setFontSize	"small" | "medium" | "large"
Font family	setFontFamily	string (5 fonts)
Border radius	setBorderRadius	"sharp" | "rounded" | "extra-round"
Table padding	setTablePadding	number (0–10)
Table text align	setTableTextAlign	"left" | "center" | "right"
Scrollbar style	setScrollbarStyle	ScrollbarStyle
Shadow intensity	setShadowIntensity	ShadowIntensity
Glass intensity	setGlassIntensity	GlassIntensity
Animation speed	setAnimationSpeed	AnimationSpeed
Gradient style	setGradientStyle	GradientStyle
Surface style	setSurfaceStyle	SurfaceStyle
Button style	setButtonStyle	ButtonStyle
Border width	setBorderWidth	BorderWidth
Table header style	setTableHeaderStyle	TableHeaderStyle
Icon style	setIconStyle	IconStyle
Input style	setInputStyle	InputStyle

Adding a new theme dimension

Follow this four-step pattern (see CLAUDE.md for the full annotated pattern):

1. ThemeContext.tsx — add state + setter + loadSetting() call
2. ThemeBuildConfig (themes/utils/index.ts) — add the new property to the interface
3. buildTheme() (themes/utils/index.ts) — apply the value as a MUI component override or palette property
4. ThemeCustomizationDrawer.tsx — add a UI control for the new dimension

Resetting to defaults

const { resetToDefaults } = useThemeContext();

<Button onClick={resetToDefaults}>Reset theme</Button>;