Theming

Cotton supports light and dark modes out of the box with zero configuration. Themes are managed via the TokenProvider component.

Basic Setup

import { TokenProvider } from '@akrade/cotton-ui';

function App() {
  return (
    <TokenProvider colorScheme="system">
      <YourApp />
    </TokenProvider>
  );
}

Color Scheme Options

"light" — Force light mode
"dark" — Force dark mode
"system" — Follow OS preference (recommended)

Theme Persistence

TokenProvider automatically persists the user's theme choice to localStorage. On subsequent visits, the user's preference is restored.

Programmatic Control

import { useTheme } from '@akrade/cotton-ui';

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

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      Toggle Theme
    </button>
  );
}

CSS Data Attributes

Cotton sets data-theme on the html element:

<html data-theme="dark">
  <!-- Your app -->
</html>

Use this for custom theme-aware styles:

[data-theme="dark"] .my-component {
  /* Dark mode styles */
}

[data-theme="light"] .my-component {
  /* Light mode styles */
}

Custom Themes (Advanced)

For advanced customization, use @akrade/cotton-ux to create custom themes with your own tokens:

import { createTheme } from '@akrade/cotton-ux';

const customTheme = createTheme({
  colors: {
    primary: '#6366f1',
    // ... custom colors
  },
});