Configuration

The best way to configure the library is during installation, but you can also manually adjust the providers in your app.config.ts.

Provider Configuration

Import provideThemeStack and add it to your providers array:

import { provideThemeStack } from 'ngx-theme-stack';

export const appConfig: ApplicationConfig = {
  providers: [
    provideThemeStack({
      themes: ['light', 'dark', 'sunset'], // Your theme identifiers
      defaultTheme: 'system',              // Initial fallback ('system' resolves via matchMedia)
      mode: 'class',                       // 'class', 'attribute' or 'both'
      strategy: 'critters',                // 'critters' (SSR) or 'blocking' (Standard SPA)
      storageKey: 'ngx-theme-stack'        // LocalStorage key
    })
  ]
};

Configuration Options

Option	Type	Default	Description
`themes`	`string[]`	`['light', 'dark', 'system']`	Custom themes to add. Merged with built-ins — e.g. `['sepia']` resolves to `['system', 'light', 'dark', 'sepia']`.
`defaultTheme`	`string`	`'system'`	Theme used on first visit or when no preference is saved.
`mode`	`NgMode`	`'class'`	How the theme is applied: `class`, `attribute` (`data-theme`), or `both`.
`strategy`	`NgStrategy`	`'critters'`	CSS delivery strategy: `critters` inlines vars in `<head>` (zero requests); `blocking` loads `themes.css` as a render-blocking file.
`storageKey`	`string`	`'ngx-theme-stack'`	Key used to persist theme preference in `localStorage`.

Whenever you update these settings manually in app.config.ts, you should run the sync command to ensure your index.html is updated with the correct anti-flash script logic. In most setups, this is handled automatically on builds/runs via package manager hooks.

Type-Safe Themes

If you want full type-safety for your themes in your services, you should mark the themes array as const. This allows the library to infer the exact theme names in your signals.

provideThemeStack({
  themes: ['sepia', 'ocean', 'forest'] as const,
  defaultTheme: 'sepia'
})

With this configuration, any service you inject will know exactly which themes are available.

Sync Command

The sync command refreshes the inline script in your index.html to match your current configuration.

Automatic Synchronization

The ng add installer automatically registers package manager script hooks in your package.json to keep your theme options synchronized:

"scripts": {
  "ngx-theme-stack:sync": "ng generate ngx-theme-stack:sync --project YOUR_PROJECT_NAME",
  "prestart": "npm run ngx-theme-stack:sync",
  "prebuild": "npm run ngx-theme-stack:sync"
}

This runs the synchronization script automatically before local serving (npm start, pnpm start, yarn start, bun start) and production builds (ng build).

Manual Synchronization

If you bypass npm scripts (e.g. running ng serve directly from the CLI) or change settings without running a server or build, you can run the sync command manually:

# Using the package.json script (recommended)
npm run ngx-theme-stack:sync

# Directly using the schematic
ng generate ngx-theme-stack:sync --project YOUR_PROJECT_NAME