Theme Switch Component

Overview

Theme Switch spreads the new theme from the button in a circular reveal, sweeps it across the viewport, or fades it in, so users keep their place. The sun and moon icons spin or orbit as the theme changes, and an optional tooltip labels the icon-only button.

Use it when a product offers both light and dark modes and lets users choose, such as dashboards, docs, portfolios, and developer tools. The theme itself matters more than the transition.

Theme and Interaction Customisation

Adjust the button’s background, border, and text treatment, use an outline style, and add an optional tooltip. Transitions can be a circular reveal, swipe, or fade with adjustable duration, and the icons can spin or orbit.

Example Production Use Case

A SaaS analytics dashboard can put Theme Switch in its header. Switching to dark mode reveals from the button across charts and tables while filters and the current view stay exactly as they were.

A documentation site can use the fade transition so readers switch to dark mode for long sessions without a jarring flash.

A creative portfolio can lean into the orbiting icon and swipe reveal as a signature detail that shows off two distinct visual treatments of the same work.

Best Used For

• SaaS dashboards.
• Developer tools and code editors.
• Content websites, blogs, and knowledge bases.
• Productivity applications.
• Creative portfolios.
• Compact application headers and toolbars.
• Design system showcases.

Not For

Skip it if the product only has one complete theme, since a half-built dark mode feels inconsistent.

Avoid page-wide reveals where colour changes must be instant for operational or accessibility reasons.

It can’t hide incomplete theming in charts or dialogs, and products bound by an organisation-wide appearance policy may not need a user toggle.

Performance Budget

Switch themes through a shared class or token system rather than re-rendering the app, and keep transitions short. Test reveals on heavy pages and low-powered phones, prevent stacking animations on repeated clicks, and fall back to an instant switch without View Transitions or with reduced motion.

Accessibility and Mobile

Use a button with a clear accessible name, either a stable label with aria-pressed or an action label that updates, plus Enter and Space activation and visible focus. On mobile, keep it easy to tap and ensure the reveal covers the whole viewport. Both themes need good contrast, and reduced motion should disable reveals and icon rotation.

Common Mistakes

• Revealing the theme before its styles are ready.
• Breaking theme switching in browsers without View Transitions.
• Starting the circular reveal from the wrong origin.
• Letting rapid clicks leave an intermediate theme.
• Flashing the wrong theme on initial load.
• Styling only the page background.
• Relying on the icon alone to explain the control.
• Ignoring reduced-motion preferences.