MantineProvider manages the color scheme context in your application. You can configure the default color scheme value with the defaultColorScheme prop; possible values are light , dark , and auto (system color scheme is used). The default value is light .
When MantineProvider is mounted, it sets a data-mantine-color-scheme attribute on the <html /> element to the value that the user has previously selected or to the value of the defaultColorScheme prop. The data-mantine-color-scheme attribute is used in all component styles to determine which colors each component should use.
The useMantineColorScheme hook can be used to get and set the current color scheme value:
useComputedColorScheme returns a computed color scheme value—it returns either light or dark . It can be used to implement color scheme toggle logic:
By default, transitions on all elements are disabled when the color scheme changes to avoid inconsistent animations. To enable transitions during color scheme changes, set the keepTransitions: true option on the useMantineColorScheme hook:
By default, the color scheme value is stored in local storage, and its value is saved in state before the component is mounted to avoid a flash of inaccurate color scheme. This means that the color scheme value can be different on the client and server, as the server does not have access to local storage and always uses the default value.
If you have server-side rendering in your application (for example, if you use Next.js or React Router ), then you cannot use the colorScheme value in your application to avoid hydration issues. Instead, you can use the dark and light mixins from postcss-preset-mantine to generate styles that will hide elements based on the color scheme value:
colorScheme for client-only applications
You can safely use the colorScheme value in client-only applications (for example, Vite or create-react-app applications). In this case, there is no hydration, and thus no hydration error can occur.
The ColorSchemeScript component renders a script tag that sets the data-mantine-color-scheme attribute on the <html /> element to the user's selected value or to the defaultColorScheme prop value before hydration. It is used to avoid a flash of inaccurate color scheme in server-side rendered applications, for example Next.js or React Router . Follow the framework-specific guides to learn where to render the ColorSchemeScript component.
You can add any additional props to the <script /> tag generated by the ColorSchemeScript component, for example, you can add a nonce attribute:
Set defaultColorScheme="auto" on MantineProvider and ColorSchemeScript to use the system color scheme. In this case, the color scheme value will be controlled by the user's OS:
By default, the color scheme value is stored in local storage, but you can implement your own color scheme manager to store the value in any other external storage.
A color scheme manager must have the following methods:
Usually, it's better to wrap the color scheme manager in a creator function to provide a way to configure it. Default local storage-based color scheme manager example:
Then the custom color scheme manager can be passed to MantineProvider :
The default color scheme value is used when the user has not selected any color scheme yet. It is required to be set both on MantineProvider and ColorSchemeScript . If defaultColorScheme is not set, then light is used.
You can force the color scheme value to be either light or dark with forceColorScheme prop. It is required to be set both on MantineProvider and ColorSchemeScript . If forceColorScheme is set, then defaultColorScheme and colorSchemeManager are ignored. When forceColorScheme is set, it's not possible to change the color scheme value with the setColorScheme function.
All Mantine components support lightHidden and darkHidden props that can be used to hide a component in a specific color scheme:
If you need to support users with disabled JavaScript, you need to set the data-mantine-color-scheme attribute on the <html /> element manually.
Example with Next.js app router that supports disabled JavaScript: