React Providers

The React implementation of the design system uses React context to make certain aspects configurable through context providers.

App Provider

The <AppProvider> is used to configure the design system at the application level and should wrap your whole application if used. Because it extends the <ThemeProvider>, it will be treated as the root-level theme configuration.

For instance, to use your own router link and force a light color scheme:

Example: light scheme and custom router link

import React from 'react';
import ReactDOM from 'react-dom';
import { Link } from 'react-router-dom';
import { AppProvider } from '@wwnds/react';
import App from './App';

const rootElement = document.getElementById('root');
ReactDOM.render(
	<React.StrictMode>
		<AppProvider
			linkComponent={Link}
			colorScheme="light"
			ignoreOSColorScheme
		>
			<App />
		</AppProvider>
	</React.StrictMode>,
	rootElement,
);

Name	Description	Type
colorScheme	The desired color scheme. "light" – dark text on light background. "dark" – light text on dark background. "inverse" – the opposite color scheme from the parent <ThemeProvider>. Cannot be used on the root <ThemeProvider>. undefined – use the user's preferred color scheme. If ignoreOSColorScheme is true, "light" will be used as a fallback. Reference: prefers-color-scheme media query.	ColorScheme | "inverse"
ignoreOSColorScheme	If set, the user's operating system color scheme setting will be ignored.	boolean
onColorSchemeChange	A callback function that will trigger any time the colorScheme changes. Use to update the color scheme store when it's changed by the user.	((scheme: ColorScheme) => void)
linkComponent	When defined, the design system <Link> component will render with the provided link component instead of its own render function.	LinkComponent

Theme Provider

The <ThemeProvider> sets a color scheme context, setting a data-color-scheme attribute ("light" or "dark") that can be used to theme children. @wwnds/core uses this to set color role token assignments, but you can use it however you like with a [data-color-scheme='light|dark'] selector.

The <ThemeProvider> can be nested, and the highest-level provider will be used as the root provider. When undefined, the root provider will use the color scheme that the user prefers. And by default, the root color scheme will update whenever the user changes their preferred color scheme in their operating system settings. This can be disabled by setting ignoreOSColorScheme.

When nested inside a parent <ThemeProvider>, the "inverse" value will use the inverse of the parent color scheme context.

Live Editor

<ThemeProvider colorScheme="dark">
	<p className="themed">Dark</p>
	<ThemeProvider colorScheme="inverse">
		<p className="themed">Inverted</p>
		<ThemeProvider colorScheme="inverse">
			<p className="themed">Double inverted</p>
		</ThemeProvider>
	</ThemeProvider>
</ThemeProvider>

Result

Loading...

Name	Description	Type
colorScheme	The desired color scheme. "light" – dark text on light background. "dark" – light text on dark background. "inverse" – the opposite color scheme from the parent <ThemeProvider>. Cannot be used on the root <ThemeProvider>. undefined – use the user's preferred color scheme. If ignoreOSColorScheme is true, "light" will be used as a fallback. Reference: prefers-color-scheme media query.	ColorScheme | "inverse"
ignoreOSColorScheme	If set, the user's operating system color scheme setting will be ignored.	boolean
onColorSchemeChange	A callback function that will trigger any time the colorScheme changes. Use to update the color scheme store when it's changed by the user.	((scheme: ColorScheme) => void)

useTheme hook

In addition to the theme provider, the useTheme hook can be used by components to update the current context's color scheme.

Example: toggle dark mode with a switch

import { Switch, useTheme } from '@wwnds/react';

export const SchemeToggle = () => {
	const { colorScheme, setColorScheme } = useTheme();
	const isDark = colorScheme === 'dark';

	const onToggleChange = (checked: boolean) => {
		setColorScheme((checked) ? 'dark' : 'light');
	};

	return (
		<Switch
			label="Dark mode"
			checked={isDark}
			onToggle={onToggleChange}
		/>
	);
}