Color Mode

Yamada UI includes built-in support for managing the color mode of your application.

All components in Yamada UI support dark mode. Depending on the scenario, you may need to adapt components to the color mode.

Setup

To make dark mode work correctly, you need to do two things:

Set initialColorMode in the config.
Add ColorModeScript to your application.

Customize the Config

Color mode is set in the default config.

Here are the actual values defined.

config.ts

export const config: ThemeConfig = {
  initialColorMode: "light",
}

Copied!

initialColorMode: The initial value of the color mode when the user first accesses the application (or after storage is reset). It accepts three values.
- light: Light mode.
- dark: Dark mode.
- system: Retrieves the color mode from the operating system (OS).

import { UIProvider, extendConfig } from "@yamada-ui/react"

export const config: ThemeConfig = {
  initialColorMode: "system",
}

const customConfig = extendConfig(config)

const App = () => {
  return (
    <UIProvider config={customConfig}>
      <YourApplication />
    </UIProvider>
  )
}

Copied!

Add `ColorModeScript`

To make the color mode work properly, you need to add ColorModeScript within the head or body.

This is because the color mode is implemented using localStorage or cookies, and it is necessary to synchronize correctly at the time of page loading.

For Create React App

index.tsx

import { createRoot } from "react-dom/client"
import { App } from "./app"
import { UIProvider, getColorModeScript, defaultConfig } from "@yamada-ui/react"

const injectColorModeScript = () => {
  const scriptContent = getColorModeScript({
    initialColorMode: defaultConfig.initialColorMode,
  })

  const script = document.createElement("script")

  script.textContent = scriptContent

  document.head.appendChild(script)
}

injectColorModeScript()

const container = document.getElementById("app")

const root = createRoot(container!)

root.render(
  <UIProvider>
    <App />
  </UIProvider>,
)

Copied!

Please pass the same initialColorMode to props as in your config. If you have your own config, please pass its initialColorMode.

For Next.js

_document.tsx

import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript, defaultConfig } from "@yamada-ui/react"

export default function Document() {
  return (
    <Html lang="en">
      <Head />

      <body>
        <ColorModeScript initialColorMode={defaultConfig.initialColorMode} />
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Copied!

Depending on the project, you may need to retrieve values from cookies. In that case, use createColorModeManager("cookie").

_document.tsx

import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript, defaultConfig } from "@yamada-ui/react"

export default function Document() {
  return (
    <Html lang="en">
      <Head />

      <body>
        <ColorModeScript
          type="cookie"
          nonce="testing"
          initialColorMode={defaultConfig.initialColorMode}
        />
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Copied!

_app.tsx

import type { AppProps } from "next/app"
import { UIProvider, createColorModeManager } from "@yamada-ui/react"

const colorModeManager = createColorModeManager("cookie")

export default function App({ Component, pageProps }: AppProps) {
  return (
    <UIProvider colorModeManager={colorModeManager}>
      <Component {...pageProps} />
    </UIProvider>
  )
}

Copied!

Please pass the same initialColorMode to props as in your config. If you have your own config, please pass its initialColorMode.

For the case of App Router, please check here.

Add `colorModeManager`

For sites rendered on the server side, such as Next.js, you may want to include the color mode in the request to avoid changes during hydration.

If you are not using server-side rendering, you do not need to follow these steps. Yamada UI uses localStorage by default.

Prepare `getServerSideProps`

To standardize getServerSideProps across multiple pages, define getServerSideCommonProps.

import { GetServerSidePropsContext } from "next"

export const getServerSideCommonProps = ({
  req,
}: GetServerSidePropsContext) => {
  return {
    props: {
      cookies: req.headers.cookie ?? "",
    },
  }
}

Copied!

Set `cookies` in `colorModeManager`

Set ssr and cookies in createColorModeManager.

_app.tsx

import type { AppProps } from "next/app"
import { UIProvider, createColorModeManager } from "@yamada-ui/react"

export default function App({ Component, pageProps }: AppProps) {
  const { cookies } = pageProps
  const colorModeManager = createColorModeManager("ssr", cookies)

  return (
    <UIProvider colorModeManager={colorModeManager}>
      <Component {...pageProps} />
    </UIProvider>
  )
}

Copied!

Add `getServerSideProps`

Add the previously created getServerSideCommonProps to each page.

index.tsx

import { getServerSideCommonProps } from "../get-server-side-props.ts"
import { Button } from "@yamada-ui/react"

export default function Index() {
  return <Button>Click me!</Button>
}

export const getServerSideProps = getServerSideCommonProps

Copied!

Color Mode Syntax

To set the style for color mode, simply pass an array to the style's props.

Define the style value you want to set for light mode as the first argument.
Define the style value you want to set for dark mode as the second argument.

Editable example

<Box w="full" p="md" bg={["primary", "secondary"]} color="white">
  This is Box
</Box>

Copied!

Switching Color Modes

If you want to change the color mode within the application, use changeColorMode or toggleColorMode.

changeColorMode: Sets any color mode.
toggleColorMode: Switches to dark mode if it's light mode, and to light mode if it's dark mode.

Editable example

const { colorMode, changeColorMode, toggleColorMode } = useColorMode()

return (
  <Wrap gap="md">
    <Button onClick={() => changeColorMode("light")}>Light Mode</Button>
    <Button onClick={() => changeColorMode("dark")}>Dark Mode</Button>
    <Button onClick={() => changeColorMode("system")}>System</Button>
    <Button onClick={toggleColorMode}>
      {colorMode === "light" ? "Switch to Dark" : "Switch to Light"} Mode
    </Button>
  </Wrap>
)

Copied!

Color Mode Utilities

Yamada UI provides convenient custom hooks for color mode.

Use `useColorMode`

To get the current color mode within a component, use useColorMode.

Editable example

const { colorMode, internalColorMode } = useColorMode()

return (
  <Text>
    The current colorMode is "{colorMode}", internal colorMode is "
    {internalColorMode}"
  </Text>
)

Copied!

colorMode returns the current light or dark.
internalColorMode returns the current light, dark, or system.

Use `useColorModeValue`

useColorModeValue is a custom hook that takes the light mode value as the first argument and the dark mode value as the second argument, returning the value for the current color mode.

Editable example

const { colorMode } = useColorMode()
const bg = useColorModeValue("blackAlpha.800", "whiteAlpha.800")
const color = useColorModeValue("whiteAlpha.800", "blackAlpha.800")

return (
  <Box p="md" bg={bg} color={color}>
    The current colorMode is "{colorMode}"
  </Box>
)

Copied!

This is suitable for setting the style of components from libraries other than Yamada UI.

Edit this page on GitHub

PreviousResponsive Styles NextCSS Custom Properties (Variables)

Color Mode

Customize the Config

Add ColorModeScript

For Create React App

For Next.js

Add colorModeManager

Prepare getServerSideProps

Set cookies in colorModeManager

Add getServerSideProps

Color Mode Syntax

Switching Color Modes

Color Mode Utilities

Use useColorMode

Use useColorModeValue

Add `ColorModeScript`

Add `colorModeManager`

Prepare `getServerSideProps`

Set `cookies` in `colorModeManager`

Add `getServerSideProps`

Use `useColorMode`

Use `useColorModeValue`