Getting Started

A simple and powerful headless theme manager for Angular 20+. Built for performance and SSR support.

Installation

To install the library and configure it automatically in your project, run:

ng add ngx-theme-stack

Installation Modes

Since ng add is currently not supported for Bun environments, please use this two-step process:

Install:
Terminal window
```
bun add ngx-theme-stack
```
Configure:
Terminal window
```
ng generate ngx-theme-stack:ng-add
```

This ensures Bun handles the dependency management while the schematic automates the code configuration (providers, index.html, tokens, etc.).

When running ng add, you will be presented with two configuration options:

Quick Mode
Custom Mode

Applies default configuration instantly.
Initial theme: system.
Apply mode: class (adds the theme class to the <html> element).
Available themes: ['light', 'dark', 'system'].
Strategy: critters (Zero-flash via CSS inlining).

Choose which themes to include (e.g., if you have a blue or high-contrast theme).
Configure the default theme upon app startup.
Change the localStorage key where the theme choice is saved.
Decide how to apply themes: via classes (class), attributes (data-theme), or both.
Pick your strategy: critters for modern SSR/SSG apps or blocking for standard SPA.

What does `ng add` do?

To provide a “Zero Config” experience, the installation command automates the following:

Directory.agents/
- Directoryskills/
  - Directoryngx-theme-stack/
    SKILL.md (Optional AI Agent Skill)
Directorypublic/
- …
Directorysrc/
- Directoryapp/
  - app.config.ts (Configure providers here)
  - app.routes.ts
  - app.ts
  - app.html
  - app.css
- index.html (Injects anti-flicker script and marker)
- main.ts
- styles.css
- themes.css (New! Base file with CSS variables)
angular.json (Registers styles and critical CSS optimization)
package.json (Adds “ngx-theme-stack:sync”, “prestart”, and “prebuild” scripts)
tsconfig.json

Basic Usage

Inject the services in your components using Angular’s inject() function.

ngx-theme-stack provides different utilities to interact with themes:

Toggle Ideal for quick light/dark theme switches.

Select Perfect for dropdown menus with multiple themes.

Cycle Useful for buttons that rotate through all themes.

Custom Total control over theme logic.

Security & Trust

Security is a core design principle for ngx-theme-stack. The library achieves a 100/100 score on Socket.dev across all main categories (Supply Chain Security, Vulnerability, Quality, Maintenance, and License):

Supply Chain Security: Strict dependency scanning and pinning via overrides to prevent malicious updates.
Vulnerabilities: Zero known vulnerabilities in both production and development environments.
Runtime Safety: The anti-flash blocking script validates all theme inputs against a strict regular expression (/^[a-zA-Z][a-zA-Z0-9_-]*$/) and checks against configured themes before making any DOM updates, preventing injection attacks.
Static Template Compilation: Schematic templates are converted directly to TypeScript assets to eliminate raw markdown parsing alerts and ensure build-time safety.

Next Steps

Now that you have the library installed, you can:

Configure Provider Learn how to initialize the provider in your app.config.ts

Add CSS variables Define your themes using standard CSS variables.

API Reference See all available methods and services.