Search documentation v0.6.1

Theme Switcher

Easily switch between predefined themes on your page

Source ↗️ Report Issue ↗️

The ThemeSwitcher component allow users to toggle between different visual themes of your application/website, such as light mode and dark mode. Use them to enhance user experience and accessibility.

To use the ThemeSwitcher component, you must first have themes setup in your setup mixin.

Make sure you have themes setup first
@import 'webcoreui/styles';
@include setup((
...
themes: (
dark: '.theme-dark',
light: '.theme-light',
midnight: '.theme-blue',
amber: '.theme-yellow'
)
));
To learn more on how to configure themes, visit the Themes documentation.
Preview
How to use ThemeSwitcher in Astro
---
import { ThemeSwitcher } from 'webcoreui/astro'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light',
'#415A77': 'theme-blue',
'#FCBA28': 'theme-yellow'
}
---
<ThemeSwitcher themes={themes} />
How to use ThemeSwitcher in Svelte
<script>
import { ThemeSwitcher } from 'webcoreui/svelte'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light',
'#415A77': 'theme-blue',
'#FCBA28': 'theme-yellow'
}
</script>
<ThemeSwitcher themes={themes} />
How to use ThemeSwitcher in React
import React from 'react'
import { ThemeSwitcher } from 'webcoreui/react'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light',
'#415A77': 'theme-blue',
'#FCBA28': 'theme-yellow'
}
const Component = () => <ThemeSwitcher themes={themes} />
export default Component

When using the component, it’ll attach the necessary class to your body tag that’ll active the theme for you. It’ll also create a w-theme cookie and local storage item that you can reference to set the theme on page load either on your server or in the client.

The component only sets the theme in the current session. Use the w-theme cookie or local storage item to reset the theme on page load.
Make sure you set the previously chosen theme
<script>
document.body.className = localStorage.getItem('w-theme') || 'theme-dark'
</script>

Toggles

If you only have two themes, such as a dark and light theme, you can turn the component into a single toggle button by setting the toggle prop to true:

<ThemeSwitcher
themes={themes}
toggle={true}
/>

Toggles with Icons

To complement the toggle functionality visually with custom icons, you can use named slots for Astro/Svelte component, and additional props for React components:

---
import { ThemeSwitcher, Icon } from 'webcoreui/astro'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
---
<ThemeSwitcher
themes={themes}
toggle={true}
>
<Icon type="moon" slot="primaryIcon" />
<Icon type="sun" slot="secondaryIcon" />
</ThemeSwitcher>
<script>
import { ThemeSwitcher, Icon } from 'webcoreui/svelte'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
</script>
<ThemeSwitcher
themes={themes}
toggle={true}
>
<Icon type="moon" slot="primaryIcon" />
<Icon type="sun" slot="secondaryIcon" />
</ThemeSwitcher>
import React from 'react'
import { ThemeSwitcher, Icon } from 'webcoreui/react'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
const Component = () => (
<ThemeSwitcher
themes={themes}
toggle={true}
primaryIcon={<Icon type="moon" />}
secondaryIcon={<Icon type="sun" />}
/>
)
export default Component

Use the primaryIcon and secondaryIcon slots for Astro/Svelte components. When using in React, use the primaryIcon and secondaryIcon props instead. The same approach can be used to create toggles with custom images instead of icons. Simply replace the Icon component with an img tag:

---
import { ThemeSwitcher } from 'webcoreui/astro'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
---
<ThemeSwitcher
themes={themes}
toggle={true}
>
<img src="/path/to/img.png" slot="primaryIcon" />
<img src="/path/to/img1.png" slot="secondaryIcon" />
</ThemeSwitcher>
<script>
import { ThemeSwitcher } from 'webcoreui/svelte'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
</script>
<ThemeSwitcher
themes={themes}
toggle={true}
>
<img src="/path/to/img.png" slot="primaryIcon" />
<img src="/path/to/img1.png" slot="secondaryIcon" />
</ThemeSwitcher>
import React from 'react'
import { ThemeSwitcher } from 'webcoreui/react'
const themes = {
'#252525': 'theme-dark',
'#DDD': 'theme-light'
}
const Component = () => (
<ThemeSwitcher
themes={themes}
toggle={true}
primaryIcon={<img src="/path/to/img.png" />}
secondaryIcon={<img src="/path/to/img1.png" />}
/>
)
export default Component

Sizes

To change the size of your ThemeSwitcher component, override the following CSS variable:

html body {
--w-theme-switcher-size: 20px;
}

Alternatively, set the size prop to change the size on individual components:

<ThemeSwitcherExample
themes={toggleThemes}
/>
<ThemeSwitcherExample
themes={toggleThemes}
size={25}
/>
<ThemeSwitcherExample
themes={toggleThemes}
size={30}
/>

API

type ThemeSwitcherProps = {
themes: {
[key: string]: string
}
toggle?: boolean
size?: number
className?: string
}
type ReactThemeSwitcherProps = {
primaryIcon?: React.ReactNode
secondaryIcon?: React.ReactNode
} & ThemeSwitcherProps
PropPurpose
themes Define your themes that have been set up using the Setup mixin.
toggle Turns the switcher into a one button toggle. Use if you only have two themes.
size Sets the size of the switcher. Defaults to 20px.
className Pass additional CSS classes for the theme switcher.

For React components, instead of using slots, use the primaryIcon and secondaryIcon props to pass custom icons to your component.


Request improvement for this page