--- type: ai-agent-documentation version: 2.0 component: ThemeSwitch status: stable audience: ai-coding-agents-only human-readable: false category: utility framework-support: - vanilla: true - react: true - vue: true - angular: true - svelte: true --- # Component: ThemeSwitch DEFINITION: The ThemeSwitch component provides a user interface element for toggling between light and dark themes. It automatically saves user preference and applies the theme to the `` element. ## Installation ```bash npm install @pm7/core ``` ### CSS & JavaScript Import REQUIRED: Import both the CSS and the main JavaScript file. ```javascript // ES modules import '@pm7/core/dist/pm7.css'; import '@pm7/core'; // Imports and initializes all components // HTML ``` ## Required Structure The ThemeSwitch component is initialized on a `div` element with the `data-pm7-theme-switch` attribute. The component's internal structure (button, thumb, icons) is generated by JavaScript. ```html
``` ### Structural Rules - **ALWAYS**: The container MUST be a `div` element. - **ALWAYS**: The container MUST have the `data-pm7-theme-switch` attribute. - **NEVER**: Manually create the internal structure (buttons, spans, icons) of the theme switch. It is generated by JavaScript. ## JavaScript API ### Initialization Initialization is automatic for theme switches present in the DOM when `@pm7/core` is imported. For dynamically added theme switches, re-initialization is required. ```javascript // For components added after initial page load window.PM7.init(); ``` ### Instance Access ```javascript const element = document.querySelector('[data-pm7-theme-switch]'); const instance = element.PM7ThemeSwitch; ``` ### Methods | Method | Parameters | Return Type | Description | |---|---|---|---| | `setTheme` | `theme: 'light' | 'dark'` | `void` | Sets the theme to 'light' or 'dark'. | | `getTheme` | `(none)` | `'light' | 'dark'` | Returns the current active theme. | | `toggle` | `(none)` | `void` | Toggles the theme between light and dark. | | `destroy` | `(none)` | `void` | Removes all event listeners and cleans up the instance. | ### Options Options can be set via `data-` attributes on the `data-pm7-theme-switch` element. | Attribute | Type | Default | Description | |---|---|---|---| | `data-default-theme` | `'light' | 'dark'` | `system preference` | Overrides the initial theme detection. | | `data-storage-key` | `string` | `'pm7-theme'` | Custom key for storing theme preference in `localStorage`. | | `data-apply-to-root` | `boolean` | `true` | If `false`, prevents the component from adding the `dark` class to ``. | ### Events | Event | When | Detail | Bubbles | |---|---|---|---|---| | `pm7:theme-switch:change` | After the theme changes | `{ theme: 'light' | 'dark' }` | YES | ## Attributes See /docs/ATTRIBUTES.md for cross-component attribute relationships. | Attribute | Component(s) | Values | Required | Effect | |---|---|---|---|---| | `data-pm7-theme-switch` | ThemeSwitch | presence | YES | Initializes ThemeSwitch component. | | `data-default-theme` | ThemeSwitch | `light`, `dark` | NO | Overrides system preference for initial theme. | | `data-storage-key` | ThemeSwitch | string | NO | Custom key for storing theme preference in `localStorage`. | | `data-apply-to-root` | ThemeSwitch | `true`, `false` | NO | Controls whether `dark` class is applied to ``. | | `aria-checked` | ThemeSwitch | `true`, `false` | AUTO | Indicates the current checked state of a switch. | | `role` | ThemeSwitch | `switch` | AUTO | Defines the purpose or nature of an element. | ## CSS Classes | Class | Required | When | Effect | |---|---|---|---| | `.pm7-theme-switch` | AUTO | Applied by JS to the main container | Base styling for the theme switch. | | `.pm7-theme-switch--sm` | NO | For a smaller switch | Reduces the size of the switch. | | `.pm7-theme-switch--lg` | NO | For a larger switch | Increases the size of the switch. | | `.pm7-theme-switch--disabled` | NO | To disable user interaction | Styles the switch as disabled. | | `.pm7-theme-switch--no-hover` | NO | To remove hover effects | Disables visual feedback on hover. | | `.pm7-theme-switch--label-start` | NO | To position label before switch | Aligns the label to the left of the switch. | | `.pm7-theme-switch--fixed` | NO | For a fixed position switch with label | Positions the switch at a fixed screen location with a label. | | `.pm7-theme-switch--fixed-icon` | NO | For a fixed position icon-only switch | Positions the switch at a fixed screen location as an icon. | ## Patterns ### Pattern: Basic Theme Switch ```html
``` ### Pattern: Theme Switch with Label ```html
Dark Mode
``` ### Pattern: Small Theme Switch ```html
``` ### Pattern: Fixed Position Icon Switch ```html
``` ### Pattern: Flicker Prevention Script This script MUST be placed in the `` of your HTML, before any stylesheets, to prevent a flash of unstyled content when switching to dark mode. ```html ``` ## Anti-Patterns ### NEVER: Manually create internal elements ```html
The internal structure of the theme switch is dynamically generated by JavaScript. Manually adding these elements will lead to incorrect rendering and functionality.
``` ### NEVER: Use a ` The component expects a `div` element as its container. Using a `

Current theme: {theme}

); } ``` ### Custom Theme Switch with Label ```jsx function LabeledThemeSwitch() { const [isDark, setIsDark] = useState(false); useEffect(() => { window.PM7?.initFramework(); const handleThemeChange = (e) => { setIsDark(e.detail.theme === 'dark'); }; document.addEventListener('pm7:theme-switch:change', handleThemeChange); return () => document.removeEventListener('pm7:theme-switch:change', handleThemeChange); }, []); return (
); } ``` ### Multiple Theme Switches ```jsx function MultipleThemeSwitches() { useEffect(() => { window.PM7?.initFramework(); }, []); return ( <> {/* Header theme switch */}
{/* Settings panel theme switch */}

Appearance

Dark Mode
{/* Fixed position theme switch */}
); } ``` ### Key Points for React: - ThemeSwitch auto-generates its internal DOM structure - Never manually create the switch HTML - just provide the container - Use `pm7:theme-switch:change` event to sync with React state - PM7 handles localStorage persistence automatically - Multiple theme switches on the same page stay synchronized - The `dark` class is automatically applied to `` element ## Rules ### ALWAYS - **ALWAYS**: Use a `div` element as the container for the theme switch. - **ALWAYS**: Include the `data-pm7-theme-switch` attribute on the container `div`. - **ALWAYS**: Place the flicker prevention script in the `` of your HTML, *before* any `` tags. - **ALWAYS**: Call `window.PM7.init()` after dynamically adding a theme switch to the DOM. ### NEVER - **NEVER**: Manually create the internal HTML structure of the theme switch. - **NEVER**: Use a `