ColorModeSwitcher

A Neo-Brutalism style color mode switcher component, built on the useTheme() composable, offering three display modes.

Demo

Preview

图标模式（默认）

按钮模式

选择模式

不包含系统选项

Installation

pnpm dlx brutx-vue@latest add color-mode-switcher

Usage

Icon Mode (default)

Click the icon to cycle through light / dark / system modes.

<script setup>
import { ColorModeSwitcher } from 'brutx-ui-vue'
</script>

<template>
    <ColorModeSwitcher />
</template>

Button Mode

A combined button displaying an icon and text label. Click to cycle through modes.

<template>
    <ColorModeSwitcher display="button" />
</template>

Select Mode

A dropdown selector based on the Select component, allowing direct selection of the target mode.

<template>
    <ColorModeSwitcher display="select" />
</template>

Hiding the System Option

Control whether the "system" option is displayed via the showSystem prop. When set to false, cycling only occurs between light and dark modes.

<template>
    <ColorModeSwitcher :show-system="false" />
</template>

Edge behavior: If the current mode happens to be the hidden system (e.g. no persisted preference and the system is dark, useTheme defaults to system), icon/button clicks stay as-is without jumping; the select mode falls back to displaying the resolved color mode (resolvedColorMode), matching the actual page theme and avoiding the perceived mismatch of "a dark page with light shown in the dropdown"; programmatically passing system is no longer accepted.

Variants

Variant	Description
icon	Icon mode, displays only the icon corresponding to the current mode
button	Button mode, displays a combined button with icon and text label
select	Select mode, a dropdown selector based on the Select component

Composables

ColorModeSwitcher internally uses the useTheme() composable to retrieve and switch the current color mode. Production apps should provide a parent theme context via provideTheme(); the built-in shared singleton is only a compatibility fallback. Tests, multi-app pages, and hot-reload boundaries can call destroyBrutxFallbacks() to clear theme/toast/message fallback state together.

The color mode is persisted to localStorage (key: brutx-color-mode). When system is selected, it follows the system preference and listens for changes to the prefers-color-scheme media query.

API Reference

ColorModeSwitcher — Props

Name	Type	Default	Description
display	"button" | "icon" | "select" | undefined	"icon"	Chooses an icon button, a button labeled with the current mode, or a select. Both button modes cycle through the available modes.
Details Declared type "button" | "icon" | "select" | undefined Literal values "button" "icon" "select" Default value details Declaration 'icon' Source: packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue Resolved value "icon" Source ColorModeSwitcher.vue:19 packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue
showSystem	boolean | undefined	true	Includes system mode in the button cycle and select options. Disabling it does not change existing theme state. If the current mode is system, buttons preserve that state and the select displays the resolved light or dark mode until an available option is selected.
Details Declared type boolean | undefined Literal values false true Default value details Declaration true Source: packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue Resolved value true Source ColorModeSwitcher.vue:21 packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue
class	string | undefined	undefined	Classes passed to the active mode root: Button in button modes, or SelectRoot in select mode.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue Resolved value undefined Source ColorModeSwitcher.vue:22 packages/ui/src/components/color-mode-switcher/ColorModeSwitcher.vue

Accessibility

• Keyboard interaction: Supports Enter / Space to trigger switching
• ARIA attributes: The icon button includes a text description of the current mode