API Reference
ngx-theme-stack provides a powerful and flexible API designed around Angular Signals for maximum reactivity.
Core Service
Section titled “Core Service”CoreThemeService
Section titled “CoreThemeService”The brain of the library. It handles theme persistence, system preference detection, and DOM updates.
Signals and Properties
Section titled “Signals and Properties”| Signal / Prop | Type | Description |
|---|---|---|
selectedTheme | Signal<NgTheme> | The theme explicitly selected by the user (can be 'system'). |
resolvedTheme | Signal<NgTheme> | The actual theme applied to the DOM (resolves 'system' to 'light' or 'dark'). Never 'system'. |
isDark | Signal<boolean> | true if the resolved theme is 'dark'. false for custom themes (e.g. 'sunset'). |
isLight | Signal<boolean> | true if the resolved theme is 'light'. false for custom themes. |
isSystem | Signal<boolean> | true if the selected theme is 'system'. |
isHydrated | Signal<boolean> | true after client-side hydration. Crucial for avoiding SSR flicker. |
availableThemes | NgTheme[] | The full resolved list of themes (built-ins + custom, post-merge). |
Methods
Section titled “Methods”setTheme(theme: NgTheme): void: Changes the active theme and persists the choice. Throws anNgxThemeStackErrorif the theme is not in the valid themes list.
Convenience Services
Section titled “Convenience Services”These services internally inject CoreThemeService and expose all of its state signals so you don’t have to inject both services.
Common signals in all services:
Section titled “Common signals in all services:”selectedTheme,resolvedTheme,isDark,isLight,isSystem,isHydrated.
ThemeToggleService
Section titled “ThemeToggleService”Ideal for simple switches.
toggle(): Toggles between'dark'and'light'.
ThemeCycleService
Section titled “ThemeCycleService”Ideal for buttons that rotate through all available themes.
cycle(): Advances to the next theme in thethemesarray.availableThemes: Array of themes configured for the cycle.cycleIndex:Signal<number>- Index of the current theme.preceding:Signal<NgTheme>- The previous theme.upcoming:Signal<NgTheme>- The next theme.
ThemeSelectService
Section titled “ThemeSelectService”Ideal for dropdown menus.
select(theme: NgTheme): Sets the active theme.availableThemes: Array of all configured themes.
Configuration
Section titled “Configuration”provideThemeStack(config?: Partial<NgConfig>)
Section titled “provideThemeStack(config?: Partial<NgConfig>)”Initializes the library. Custom themes passed in config.themes are automatically merged with the default themes (['light', 'dark', 'system' ]).
NgConfig Options
Section titled “NgConfig Options”| Option | Type | Default | Description |
|---|---|---|---|
defaultTheme | NgTheme | 'system' | Theme used on first visit. |
storageKey | string | 'ngx-theme-stack' | Key for localStorage. |
mode | NgMode | 'class' | How to apply theme to <html>: 'class', 'attribute' or 'both'. |
strategy | NgStrategy | 'critters' | How theme CSS is delivered: 'critters' inlines vars in <head> (zero requests); 'blocking' loads themes.css as a render-blocking stylesheet (HTTP-cacheable). |
themes | NgTheme[] | ['light', 'dark', 'system'] | Custom themes to add. Merged with built-ins — passing ['sepia'] resolves to ['system', 'light', 'dark', 'sepia']. |
NgTheme<T>
Section titled “NgTheme<T>”A type-safe union. If used with as const in the configuration, it provides exact autocomplete.
NgMode
Section titled “NgMode”'class': Adds the theme name as a class to<html>.'attribute': Setsdata-theme="name"on<html>.'both': Applies both.
NgStrategy
Section titled “NgStrategy”'critters'(default): Inlines all theme CSS variables directly in<head>at build time via Angular’s Critters optimizer. Zero network requests. Works with CSR, SSR, and SSG.'blocking': Loadsthemes.cssas a render-blocking external stylesheet. One network request (then HTTP-cached). Required for strict CSP environments.