use-system-theme

use-system-theme is a React Hook that returns the user's preferred color scheme ('light' or 'dark') derived from the prefers-color-scheme media query and automatically updates when the system theme changes.

What is use-system-theme?

use-system-theme is a small open-source npm package created by xcv58, available under the MIT license. It provides a single React Hook, useSystemTheme, which takes an optional boolean argument isSSR and returns a string of type SystemTheme (either 'light' or 'dark'). The hook requires React version greater than 16.8.0 because it relies on React Hooks. It can be used in any React application, from single-page apps to server-side rendered ones.

Key Features

• Live system theme detection — Uses the prefers-color-scheme media query to determine whether the OS is in light or dark mode.
• Automatic re-render — Subscribes to media query change events and immediately updates the returned value when the user switches the theme at the OS level.
• SSR support — Passing true as the isSSR parameter makes the hook return 'light' during server rendering, then update to 'dark' on the client if needed, preventing hydration mismatches.
• TypeScript support — The package ships with type definitions, as shown by the declare const useSystemTheme: (isSSR?: boolean) => SystemTheme signature in the README.
• Lightweight — The npm page includes a bundlephobia badge showing the minified size, and the hook has no external dependencies beyond React.
• Broad browser compatibility — As of December 2019, all major mobile and desktop browsers support prefers-color-scheme, so the hook works without polyfills.
• Simple API — A single function call returns a primitive string, making it trivial to integrate into any component.
• MIT licensed — Free to use in commercial and personal projects.

Who is it for?

• React developers building applications that want to respect the operating system's light or dark mode preference without manually managing theme state.
• SSR and Next.js developers who need to avoid hydration mismatches when rendering theme-dependent UI on the server; the README specifically mentions the React hydrate constraint.
• UI component library authors who want to provide theme-aware defaults that react to the user's system settings out of the box.

What can you do with use-system-theme?

• Build a dark mode toggle that defaults to the system preference and lets users override it, remembering their choice in localStorage.
• Generate adaptive CSS — Dynamically switch CSS variables, class names, or inline styles based on the returned theme string.
• Create a theme context — Pass the theme from the hook through React Context so any component can consume the current system theme.
• Prevent flash of wrong theme — In SSR apps, use the isSSR flag to ensure the initial render matches the server output, then update on the client.

How does use-system-theme work?

The hook uses the browser's matchMedia API to listen to the (prefers-color-scheme: dark) media query. It reads the current value and registers a change listener so the returned state stays in sync with the OS theme. When isSSR is true, the initial state is forced to 'light' because the server cannot know the client's theme; after hydration, the listener updates it to the actual value. This approach means SSR apps may briefly flash a light theme for dark-mode users, an unavoidable consequence of React hydration.

Pros and cons

• Pros: One-line integration, automatic live updates, built-in SSR handling, typed API, minimal footprint.
• Cons: Requires React 16.8.0 or newer; for SSR apps, the initial client render is always 'light' even on dark-mode devices (the README acknowledges this as intrinsic to React hydration).

Pricing

The package is free and open source under the MIT license. There are no paid tiers or premium features.

FAQ

How do I install use-system-theme?

You can install it with yarn add use-system-theme or npm install --save use-system-theme. Then import it as import useSystemTheme from 'use-system-theme'.

Does use-system-theme support server-side rendering?

Yes, but you must call it with true as the argument: useSystemTheme(true). This makes the initial returned value 'light' to match server output. On the client, the hook updates to the real theme once hydrated.

What React version is required?

React version greater than 16.8.0 is required because the package uses React Hooks. Earlier versions do not support hooks.

What does use-system-theme return?

It returns a SystemTheme string, which is either 'light' or 'dark'. You can use this value to conditionally apply styles or render different content.

Is use-system-theme free?

Yes, it's released under the MIT license, so you can use it in personal and commercial projects without cost.