use-color-scheme

Usage

use-color-scheme hook returns preferred OS color scheme value (dark or light) and subscribes to changes:

import { Badge } from '@mantine/core';
import { useColorScheme } from '@mantine/hooks';

function Demo() {
  const colorScheme = useColorScheme();

  return (
    <Badge color={colorScheme === 'dark' ? 'blue' : 'teal'} variant="filled">
      Your system color scheme is {colorScheme}
    </Badge>
  );
}

Limitations

use-color-scheme uses use-media-query under the hood. It relies on window.matchMedia() API and always returns the specified initial value (first argument, light by default) if the API is not available (for example, during the server-side rendering).

// returns 'dark' on server side
// returns computed value on client side after mount
const colorScheme = useColorScheme('dark');

Get initial value in effect

By default, to support server-side rendering, use-color-scheme does not calculate the initial value on the first render during state initialization. Instead, the value is calculated in useEffect and updated after the parent component mounts.

If your application does not have server-side rendering, you can enable immediate calculation of the initial value by changing getInitialValueInEffect option:

const colorScheme = useColorScheme('light', { getInitialValueInEffect: true });

Definition

interface UseMediaQueryOptions {
  getInitialValueInEffect: boolean;
}

type UseColorSchemeValue = 'dark' | 'light';

function useColorScheme(
  initialValue?: UseColorSchemeValue,
  options?: UseMediaQueryOptions,
): UseColorSchemeValue

Exported types

UseColorSchemeValue and UseMediaQueryOptions types are exported from @mantine/hooks package, you can import them in your application:

import type { UseColorSchemeValue, UseMediaQueryOptions } from '@mantine/hooks';