Theme Provider

Configure entry point of the application.

Overview

The <ThemeRootProvider /> component is the entry point of the library.
It allows you to configure the global theme behavior of your application.
All components from the library must be used inside the ThemeRootProvider to work correctly.

You can locally override the theme configuration in any part of your component tree using the <ThemeChildProvider />.

ThemeRootProvider

Features

The <ThemeRootProvider /> component is used to define the global theme configuration.

It includes:

the default theme strategy (system, light, dark)
the default accent color
the default border radius
the light and dark colors used for the theme meta tag
whether the default background color is applied
whether the theme loading script is injected for SSR
whether system theme changes are detected
whether CSS transitions are enabled during theme changes
custom color palettes

This provider should be placed at the root of your application.

Usage

<script>
    // Import provider and required CSS
    import { ThemeRootProvider } from 'svxui';
    import 'svxui/styles/tokens.css';

    let { children } = $props();
</script>

<ThemeRootProvider 
    defaultStrategy="system"
    defaultColor="blue"
    defaultRadius="none"
>
    <!-- The strategy, radius, and color apply to all child components. -->
    {@render children?.()}
</ThemeRootProvider>

ThemeChildProvider

Features

The <ThemeChildProvider /> component allows you to locally override part of the global theme configuration for a subtree of components.

It can override:

the theme strategy (system, light, dark)
the accent color
the border radius

This is useful for scoped theming, such as theming a specific page, layout, or component group differently from the rest of the application.

Usage

<script>
    import { ThemeChildProvider, Panel } from 'svxui';
</script>

<ThemeChildProvider color="neutral">
    <!-- 
    The panel and button will have a neutral color by default, 
    but will inherit radius and strategy from the root theme.
    -->
    <Panel>
        <Button>button</Button>
    </Panel>
</ThemeChildProvider>

Theme Context

Features

You can update default strategy, color and radius with the theme context via useThemeRootContext.

Update theme

<script lang="ts">import { useThemeRootContext } from 'svxui';
const themeRoot = useThemeRootContext();
const strategies = ['system', 'light', 'dark'];
const radius = ['none', 'small', 'medium', 'large', 'full'];
const colors = ['neutral', 'green', 'blue', 'yellow', 'orange', 'red'];
</script>

<!-- Update strategy -->
{#each strategies as strategy (strategy)}
    <button
        class:active={themeRoot.strategy === strategy}
        onclick={() => themeRoot.setStrategy(strategy)}
    >
        {strategy}
    </button>
{/each}

<!-- Update radius -->
{#each radius as rad (rad)}
    <button
        class:active={themeRoot.radius === rad}
        onclick={() => themeRoot.setRadius(rad)}
    >
        {rad}
    </button>
{/each}

<!-- Update color -->
{#each colors as color (color)}
    <button
        class:active={themeRoot.color === color}
        onclick={() => themeRoot.setColor(color)}
    >
        {color}
    </button>
{/each}

API Reference

ThemeRootProviderProps

Extends all the standard HTML attributes of the `<div>` element.

Property	Type	Default	Description
`defaultColor`	`union`	"neutral"	Default accent color
`colorKey`	`string`		Storage key for accent color
`defaultStrategy`	`union`	ThemeSystem	Default theme strategy
`strategyKey`	`string`		Storage key for theme strategy
`defaultRadius`	`union`	"medium"	Default radius
`radiusKey`	`string`		Storage key for radius
`metaThemeColors`	`MetaThemeColorsType`	MetaThemeColors	Content colors for meta theme-color tag
`hasBackground`	`boolean`	true	Should set the background color
`track`	`boolean`	true	Should track storage change from other tab
`disableTransitions`	`boolean`	true	Should disable css transition when theme change
`disableHeadScriptInjection`	`boolean`	false	Should disable init theme script injection. This script prevent FOUC.
`customThemeColors`	`ColorMap`		Custom theme colors
`ref` $bindable	`HTMLDivElement`		Reference to the rendered DOM element.
`children`	`Snippet`		ThemeRootProvider content to render

ThemeChildProviderProps

Extends all the standard HTML attributes of the `<div>` element.

Property	Type	Description
`color`	`union`	Static Accent color or resolved from ThemeRootProvider.
`strategy`	`union`	Static theme strategy or resolved from ThemeRootProvider.
`radius`	`union`	Static radius or resolved from ThemeRootProvider.
`hasBackground`	`boolean`	Should set the background color
`ref` $bindable	`HTMLDivElement`	Reference to the rendered DOM element.
`children`	`Snippet`	ThemeChildProvider content to render

ThemeRootState

export declare class ThemeRootState {
    constructor(props: ThemeRootStateProps);
  
    /**
     * Get the current radius key used for storage
     */
    get radiusKey(): string;

    /**
     * Get the current radius
     */
    get radius(): Radius;

    /**
     * Set radius
     */
    setRadius: (radius: Radius) => void;

    /**
     * Get the current color key used for storage
     */
    get colorKey(): string;

    /**
     * Get the current color
     */
    get color(): string;

    /**
     * Set color
     */
    setColor: (color: string) => void;

    /**
     * Get the current strategy key used for storage
     */
    get strategyKey(): string;

    /**
     * Get the current strategy
     */
    get strategy(): StrategyType;

    /**
     * Set strategy
     */
    setStrategy: (strategy: StrategyType) => void;

    /**
     * Get the current system theme
     */
    get system(): ThemeType | undefined;

    /**
     * Get the current resolved theme
     */
    get theme(): "light" | "dark" | undefined;
}