Chakra UI (v2) - ColorModeProvider and ColorModeScript

Overview

This post explores the functionality differences between Chakra UI's ColorModeProvider and ColorModeScript. I originally wrote this as an answer on Stack Overflow on July 22, 2023.

ColorModeProvider

ColorModeProvider provides functionality for toggling and rendering components by color mode, like toggling component CSS classes from light to dark. Changing toggleColorMode for content not wrapped in/using the ColorModeProvider would not result in changing the content's color scheme.

Luckily, ColorModeProvider is built into ChakraProvider and ChakraBaseProvider¹,² with newer versions, and does not need to be added separately.³

ChakraProvider/ChakraBaseProvider return includes ColorModeProvider²:

return (
  <ThemeProvider theme={theme as Dict} cssVarsRoot={cssVarsRoot}>
    <ColorModeProvider
      colorModeManager={colorModeManager}
      options={theme.config}
    >
      {/* Children/additional settings omitted to save lines */}
    </ColorModeProvider>
  </ThemeProvider>
)

ColorModeScript

ColorModeScript generates and inserts a script as the first item in the root element that helps read the user's system preference for color mode, as well as set and get the user's color preference setting from local storage. It also adds/removes the appropriate body CSS class for Chakra's light/dark mode.⁴ The ColorModeScript configuration is placed as close as possible to the start of the body tag.

The documentation for ColorModeScript is quite short, so I looked at the source code⁵ and sandbox tested⁶ to understand its impact. The documentation mentions that preference storage can also be handled server-side, and if implemented server-side, the ColorModeScript does not need to be used.⁷