Theme Switcher

Easily switch between a set of predefined themes

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.

@use 'webcoreui/styles' as *;
@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

---
import { ThemeSwitcher } from 'webcoreui/astro'

const themes = {
    '#252525': 'theme-dark',
    '#DDD': 'theme-light',
    '#415A77': 'theme-blue',
    '#FCBA28': 'theme-yellow'
}
---

<ThemeSwitcher themes={themes} />

<script>
    import { ThemeSwitcher } from 'webcoreui/svelte'

    const themes = {
        '#252525': 'theme-dark',
        '#DDD': 'theme-light',
        '#415A77': 'theme-blue',
        '#FCBA28': 'theme-yellow'
    }
</script>

<ThemeSwitcher themes={themes} />

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.

<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

Prop	Purpose
`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.

<- Textarea Timeline ->

Request improvement for this page