Theme Overview

md3-react implements the Material Design 3 theme system, providing a comprehensive set of design tokens and a flexible theming mechanism.

ThemeProvider

The ThemeProvider component is the entry point for theming. It manages color mode (light/dark/system) and provides theme context to all child components.

import { ThemeProvider } from '@md3-react/theme';

function App() {
  return <ThemeProvider defaultColorMode="system">{/* Your app */}</ThemeProvider>;
}

Props

Prop	Type	Default	Description
defaultColorMode	'light' | 'dark' | 'system'	'system'	Initial color mode
storageKey	string	'md3-color-mode'	localStorage key for persisting preference
children	ReactNode	-	Child components

useTheme Hook

Access theme context anywhere in your app:

import { useTheme } from '@md3-react/theme';

function MyComponent() {
  const { colorMode, resolvedColorMode, setColorMode, themeClass } = useTheme();

  return <button onClick={() => setColorMode('dark')}>Current: {resolvedColorMode}</button>;
}

Return Value

Property	Type	Description
colorMode	'light' | 'dark' | 'system'	Current color mode setting
resolvedColorMode	'light' | 'dark'	Actual resolved color mode
setColorMode	(mode: ColorMode) => void	Function to change color mode
themeClass	string	CSS class name for the current theme

Theme Structure

md3-react follows the MD3 three-tier token system:

Reference Tokens (--md-ref-*)
    ↓
System Tokens (--md-sys-*)
    ↓
Component Tokens (--md-[component]-*)

This architecture enables powerful customization while maintaining design consistency.