<arc-theme-toggle> Overview
Guidelines
When to use
- Place ThemeToggle in a persistent location like the top bar or settings panel so users can always find it
- Use `icon-only` in dense layouts like toolbars where space is limited
- Listen to `arc-change` if you need to coordinate theme changes with a backend preference API
- Ensure your application respects the `data-theme` attribute on the document root for theme switching to work
- Set an initial `data-theme` on the HTML element during SSR to prevent flash-of-wrong-theme
When not to use
- Do not place multiple ThemeToggle instances on the same page -- they will compete for localStorage and document attributes
- Do not override the localStorage key `arc-theme` from external code without also updating the component
- Do not use ThemeToggle for toggling features unrelated to visual theme -- use Toggle for binary settings
- Do not hide the component behind a menu -- theme switching should be easily discoverable
- Avoid using ThemeToggle in iframes without ensuring the parent document also applies the theme attribute
Features
- Three-state cycle: dark -> light -> auto -> dark, covering all common theme preferences
- Animated icon transitions with scale and rotation for visually polished mode switches
- Automatic localStorage persistence under the key `arc-theme` for cross-session retention
- Sets `data-theme` attribute on the document root for immediate application-wide theme changes
- Icon-only compact mode via the `icon-only` attribute for toolbar and header usage
- Fires `arc-change` with the new theme value on every cycle for external state coordination
- Keyboard accessible with Enter and Space key support, plus visible focus ring
- Active-press scale animation (0.95) for tactile click feedback
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available — use the Web Component directly or a framework wrapper.
<arc-theme-toggle></arc-theme-toggle>import { ThemeToggle } from '@arclux/arc-ui-react';
<ThemeToggle></ThemeToggle><script setup>
import { ThemeToggle } from '@arclux/arc-ui-vue';
</script>
<template>
<ThemeToggle></ThemeToggle>
</template><script>
import { ThemeToggle } from '@arclux/arc-ui-svelte';
</script>
<ThemeToggle></ThemeToggle>import { Component } from '@angular/core';
import { ThemeToggle } from '@arclux/arc-ui-angular';
@Component({
imports: [ThemeToggle],
template: `
<ThemeToggle></ThemeToggle>
`,
})
export class MyComponent {}import { ThemeToggle } from '@arclux/arc-ui-solid';
<ThemeToggle></ThemeToggle>import { ThemeToggle } from '@arclux/arc-ui-preact';
<ThemeToggle></ThemeToggle>API
| Prop | Type | Default | Description |
|---|---|---|---|
theme | 'dark' | 'light' | 'auto' | 'auto' | The current theme mode. Automatically synced to localStorage and the document root `data-theme` attribute. |
disabled | boolean | false | Prevents cycling and reduces opacity to 40%. |
icon-only | boolean | false | Renders the button as a compact circle without the theme name label. Attribute name is `icon-only`. |
Events
| Event | Description |
|---|---|
arc-change | Fired when the theme is toggled, with { theme } detail |