Reads the user’s prefers-color-scheme media query and returns a normalized scheme value for application theming. Built on top of useMediaQuery.
Usage
import { useColorScheme } from '@kuzenbo/hooks';
function Demo() {
const colorScheme = useColorScheme();
return (
<div className={colorScheme === 'dark' ? 'dark-theme' : 'light-theme'}>
Current theme: {colorScheme}
</div>
);
}
Function Signature
function useColorScheme(
initialValue?: UseColorSchemeValue,
options?: UseMediaQueryOptions
): UseColorSchemeValue
type UseColorSchemeValue = 'dark' | 'light'
Parameters
Optional fallback scheme used before the media query resolves. Useful for SSR.
Optional media-query behavior options forwarded to useMediaQuery.options.getInitialValueInEffect
If true, reads the initial value in an effect for SSR safety. Defaults to true.
Return Value
The current color scheme preference. Returns 'dark' if the user prefers dark mode, otherwise 'light'.
Examples
Basic Theme Toggle
import { useColorScheme } from '@kuzenbo/hooks';
function ThemeProvider({ children }) {
const colorScheme = useColorScheme();
return (
<div data-theme={colorScheme}>
{children}
</div>
);
}
Dynamic Styles Based on Scheme
import { useColorScheme } from '@kuzenbo/hooks';
function Card() {
const colorScheme = useColorScheme();
const styles = {
backgroundColor: colorScheme === 'dark' ? '#1a1a1a' : '#ffffff',
color: colorScheme === 'dark' ? '#ffffff' : '#000000',
};
return (
<div style={styles}>
Card content
</div>
);
}
With Initial Value for SSR
import { useColorScheme } from '@kuzenbo/hooks';
function SSRSafeTheme() {
const colorScheme = useColorScheme('light');
return (
<div className={`theme-${colorScheme}`}>
Content
</div>
);
}
Icon Based on Color Scheme
import { useColorScheme } from '@kuzenbo/hooks';
function ThemeIcon() {
const colorScheme = useColorScheme();
return (
<div>
{colorScheme === 'dark' ? '🌙' : '☀️'}
</div>
);
}
Conditional Component Rendering
import { useColorScheme } from '@kuzenbo/hooks';
function ConditionalThemeComponent() {
const colorScheme = useColorScheme();
return (
<div>
{colorScheme === 'dark' ? (
<DarkModeComponent />
) : (
<LightModeComponent />
)}
</div>
);
}
Chart Theming
import { useColorScheme } from '@kuzenbo/hooks';
function ThemedChart() {
const colorScheme = useColorScheme();
const chartColors = colorScheme === 'dark'
? ['#60a5fa', '#34d399', '#fbbf24']
: ['#2563eb', '#059669', '#d97706'];
return <Chart colors={chartColors} data={data} />;
}
Notes
- The hook uses the
prefers-color-scheme: dark media query internally
- Returns
'light' when the media query doesn’t match or isn’t supported
- Updates automatically when the user changes their system theme preference
- Works on all modern browsers that support the
prefers-color-scheme media query