solid-theme-provider
v1.1.1
Published
Lightweight and customizable theme handler for Solid JS
Maintainers
gnomicalReadme
solid-theme-provider
A SolidJS theme provider that injects CSS variables into :root on theme switch, with built-in UI components and automatic system preference detection.
Installation
npm install solid-theme-providerQuick Start
Wrap your app in ThemeProvider and place ThemeToggle or ThemePicker anywhere inside it. No configuration required — it detects system light/dark preference automatically.
import { ThemeProvider, ThemeToggle } from "solid-theme-provider";
export default function App() {
return (
<ThemeProvider>
<nav>
<ThemeToggle label="Toggle Theme" />
</nav>
</ThemeProvider>
);
}UI Components
ThemeToggle
Toggles between the defined default light and dark themes.
| Prop | Type | Default |
| --- | --- | --- |
| label | string | — |
| classList | Record<string, boolean> | — |
ThemePicker
Opens a dropdown listing all available themes as well as a "Match System" setting.
| Prop | Type | Default |
| --- | --- | --- |
| label | string | "Theme" |
| menuPlacement | "ne" \| "se" \| "sw" \| "nw" | "se" |
| classList | Record<string, boolean> | — |
ThemeProvider Props
| Prop | Type | Default |
| --- | --- | --- |
| themes | ThemesConfig | built-in light/dark |
| default | string | system preference |
| prefix | string | "stp-" |
| calculateVariants | (name, value) => ThemeVars | hex alpha variants |
CSS Variables
On every theme switch, all variables defined in your theme's vars object are injected into :root. The built-in themes define these defaults:
--stp-background
--stp-foreground
--stp-button-radiusIn practice you'll define your own variables — any key/value pair in vars becomes a CSS custom property. Your stylesheets then consume them directly:
body, html {
background: var(--stp-background);
color: var(--stp-foreground);
}Alpha Variants
Any hex color variable automatically generates four transparent variants:
| Suffix | Opacity |
| --- | --- |
| -alpha-primary | 95% |
| -alpha-secondary | 60% |
| -alpha-tertiary | 30% |
| -alpha-quaternary | 9% |
For example, --stp-foreground generates --stp-foreground-alpha-quaternary, useful for subtle hover states and borders.
Custom Themes
import { ThemeProvider, ThemePicker } from "solid-theme-provider";
import type { ThemesConfig } from "solid-theme-provider";
const themes: ThemesConfig = {
systemThemes: { dark: "ember_night", light: "warm_light" },
themes: {
ember_night: {
config: { browserThemeColor: "#110000" },
vars: { background: "#110000", foreground: "#ddddcc", button-radius: "0.5em" },
},
warm_light: {
config: { browserThemeColor: "#f1efe5" },
vars: { background: "#fffff5", foreground: "#111100", button-radius: "0.5em" },
},
},
};
<ThemeProvider themes={themes}>
<ThemePicker />
</ThemeProvider>Note: Only one
ThemeProvidershould exist in your app. The snippet above is illustrative — in practice,themesis passed to the one and only provider you should have, the provider that wraps your app.
systemThemes maps which of your themes should be applied when following system light/dark preference. See the Custom Themes demo for a full example.
Theme Config Options
Each theme can include an optional config object:
| Field | Type | Description |
| --- | --- | --- |
| label | string | Display name in the picker (defaults to title-cased key) |
| icon | () => JSX.Element | Icon shown in the picker |
| browserThemeColor | string | Sets <meta name="theme-color"> |
| colorScheme | "light" \| "dark" | Sets color-scheme on <html> so native UI (scrollbars, form controls) match the theme. Inferred automatically for themes mapped in systemThemes. |
Advanced Usage
useTheme() exposes the full context for driving theme state from your own code:
import { useTheme } from "solid-theme-provider";
function MyComponent() {
const { currentTheme, setTheme, themes } = useTheme();
return <div>Current theme: {currentTheme()}</div>;
}See the Advanced demo for more examples including setThemesConfig for runtime theme config updates.
Image Inversion
The provider injects styles that automatically invert images when the opposing system theme is active. See the Image Invert demo for full usage details.
<!-- Invert when dark theme is active -->
<img class="invert-safe--light" src="..." />
<!-- Invert when light theme is active -->
<img class="invert-safe--dark" src="..." />
<!-- Also works via URL fragment -->
<img src="./logo.png#invert-safe--light" />