Provider

React component for theme switching and management

Availability

The Provider component is only available when you provide a themes config to createStoop(). If themes is not provided, Provider is undefined.

Usage

import { Provider } from "./stoop.theme";

function App() {
  return (
    <Provider defaultTheme="light" storageKey="my-theme">
      {/* Your app */}
    </Provider>
  );
}

Global CSS Injection

When themes config is provided, globalCss from your config is injected during createStoop() execution (module level), before React renders. Provider enables this injection but doesn't perform it - the CSS is already injected when Provider mounts.

Props

Prop	Type	Default	Description
defaultTheme	string	First theme name	Default theme name (defaults to first theme in `themes` config)
storageKey	string	"stoop-theme"	localStorage key for theme persistence
attribute	string	"data-theme"	HTML attribute name to apply theme to (e.g., "data-theme", "class")
cookieKey	string	undefined	Cookie key for theme persistence (optional, enables cookie sync with localStorage)

Theme Persistence

The Provider saves the selected theme to localStorage and restores it on page load.

When cookieKey is provided, the Provider syncs theme preferences between cookie and localStorage:

Cookie is checked first (for SSR compatibility)
localStorage is checked as fallback
Changes sync bidirectionally
Useful for SSR where localStorage isn't available

<Provider
  defaultTheme="light"
  storageKey="stoop-theme"
  cookieKey="stoop-theme"
>
  <App />
</Provider>

Enables server-side theme detection from cookies while maintaining client-side persistence in localStorage.

Custom Attribute

By default, the Provider applies the theme name to the data-theme attribute on the root element. Customize this with the attribute prop:

// Default: applies data-theme="light" or data-theme="dark"
<Provider defaultTheme="light">
  <App />
</Provider>

// Custom attribute: applies class="light" or class="dark"
<Provider defaultTheme="light" attribute="class">
  <App />
</Provider>

// Custom data attribute
<Provider defaultTheme="light" attribute="data-color-scheme">
  <App />
</Provider>

Useful for CSS attribute selectors or integrating with other systems that use different attribute names.