Color Mode

Chakra UI Vue comes with built-in support for managing color mode in your apps.

By default, most of Chakra's components are dark mode compatible. In some scenarios, you might need to make your component respond to color mode.

Introduction to Color Mode

In the recent years, operating systems (system for this guide) give user the option to choose from Light or Dark color mode. Some operating systems include also an automatic option that toggle color mode based on daylight, (day = light, night = dark).

Browsers can access this value provided by the operating system, and subscribe to the changes.

With Chakra UI Vue, you can customize the behavior of color mode.

You can decide:

• Where to store the current value, choosing from localStorage, cookies, or custom.
• If the application color mode changes based on the system's color mode.
• Whether the initial value (used on the first visit or after storage reset) is decided by the system or the developer.

Setup

To get color mode working correctly, you need to do two things:

• Update your theme config to determine how Chakra UI should manage color mode updates.
• Add the ColorModeScript to your application, and set the initial color mode your application should start with to either light, dark or system. It is light by default.

Updating the theme config

The theme config for color mode has 2 options:

• initialColorMode: The initial mode you'd like your app to start with when user visit the page for first time (or after storage reset). Can be one of dark, light or system. Default is light.
• useSystemColorMode: If true, Chakra UI subscribes to changes in system color mode. If set to false, the app's color mode is detached from the system color mode. Default is false.

// theme.js// 1. import `extendTheme` functionimport { extendTheme } from '@chakra-ui/vue-next'  
// 2. Add your color mode configconst config = {  initialColorMode: 'light',  useSystemColorMode: false,}  
// 3. extend the themeconst theme = extendTheme({ config })  
export default theme

Common Configurations

To help you define your desired behavior, here we define all common usage of the theme config. In alternative, you can use this playground to try different values.

// A.// System sets initial value.// App subscribes to system color mode changes.const config = {  initialColorMode: 'system',  useSystemColorMode: true,}  
// B.// System sets initial value.// App color mode is detached from system color mode changes.const config = {  initialColorMode: 'system',  useSystemColorMode: false,}  
// C.// You choose initial value.// App color mode is detached from system color mode changes.const config = {  initialColorMode: 'dark', // 'dark' | 'light'  useSystemColorMode: false,}  
// D.// You choose initial value.// App subscribes to system color mode changes.const config = {  initialColorMode: 'dark', // 'dark' | 'light'  useSystemColorMode: true,}

Behavior of ColorMode

The current hierarchy of how Chakra UI Vue resolves the color mode:

• Get the color mode value in the specified storage (localStorage, cookie manager or custom)
• If value doesn't exist, use the initialColorMode value specified.
  • If the initial value is system, then we'll compute the color mode using matchMedia
  • Else, we use the initial value as is.
• If user specifies useSystemColorMode: true, then we'll subscribe to color mode changes from the operating system. It is no longer used to determine the initial color mode. To achieve that, please use initialColorMode: "system"

Difference between initialColorMode='system' and useSystemColorMode

initialColorMode value is used to determine the value on first visit, or after a storage reset.

useSystemColorMode is a boolean that indicates if Chakra UI must subscribes (and updates) based on the operating system's color mode changes. If useSystemColorMode=true and operating system changes from light to dark, due to a manual or automatic switch, the page automatically changes color mode, without user interaction. If useSystemColorMode=false color mode can only be changed via the useColorMode composable.

Changing Color Mode

To manage color mode in your application, Chakra UI Vue exposes the useColorMode or useColorModeValue composables.

useColorMode

useColorMode is a composable that gives you access to the current color mode, and a function to toggle the color mode.

<script setup lang="ts">  import { useColorMode } from "@chakra-ui/vue-next"  
  const { colorMode, toggleColorMode } = useColorMode()</script>  
<template>  <CButton @click="toggleColorMode">    Toggle {{ colorMode === "light" ? "Dark" : "Light" }}
  </CButton></template>

Calling toggleColorMode anywhere in your app tree toggles the color mode from light or dark and vice versa.

useColorModeValue

useColorModeValue is a composable used to change any value or style based on the color mode. It takes 2 arguments: the value in light mode, and the value in dark mode.

import { useColorModeValue } from "@chakra-ui/vue-next"  
// Here's the signatureconst value = useColorModeValue(lightModeValue, darkModeValue)

Here's an example that changes the background-color and color using the useColorModeValue composable.

<script setup lang="ts">  import { useColorMode, useColorModeValue } from "@chakra-ui/vue-next"  
  const { toggleColorMode } = useColorMode()  
  const bg = useColorModeValue('red.500', 'red.200')  const color = useColorModeValue('white', 'gray.800')</script>  
<template>  <CBox mb="4" :bg="bg" :color="color">    This box's style will change based on the color mode.
  </CBox>  <CButton @click="toggleColorMode">    Toggle Mode
  </CButton></template>