# ๐จ ngx-theme-stack
**A simple and powerful headless theme manager for Angular.**
Built for performance, signal-driven reactivity, and SSR zero-flash support.
[](https://www.npmjs.com/package/ngx-theme-stack)
[](https://github.com/WanderleeDev/ngx-theme-stack/blob/main/LICENSE)
[](https://angular.dev/)
[](https://angular.dev/guide/signals)
[](https://angular.dev/guide/ssr)
[](#-ai-code-assistants-integration)
[๐ Live Demo](https://demo-ngx-theme-stack.wanderlee.site/) ยท [โก StackBlitz Demo](https://stackblitz.com/~/github.com/WanderleeDev/stackblitz-demo) ยท [๐ Documentation](https://ngx-theme-stack-docs.wanderlee.site/) ยท [โญ Star on GitHub](https://github.com/WanderleeDev/ngx-theme-stack)
---
## ๐ Features
- **โก Single Command Setup:** Fully configured via standard `ng add ngx-theme-stack`.
- **๐ OS Preference Auto-Detection:** Automatically synchronizes with system dark/light modes.
- **๐งฑ Angular Signals:** Built natively with reactive signals for maximum performance.
- **๐ SSR & Hydration Ready:** Guaranteed zero flicker or layout shift on startup.
- **๐ Extensible & Custom Themes:** Seamlessly add sepia, sunset, or custom color palettes.
- **๐ค AI Code Assistants Integration:** Work with AI coding assistants using the generated `SKILL.md` standard.
---
## ๐ฆ Installation
```bash
ng add ngx-theme-stack
```
> [!TIP]
> **Using Bun?**
> Since `ng add` is not supported in Bun environments, use the manual two-step process:
>
> ```bash
> bun add ngx-theme-stack
> ng generate ngx-theme-stack:ng-add
> ```
---
## ๐ ๏ธ Quick Start
Below is a simple example of a standalone theme toggle component.
> [!TIP]
> **๐ก Architecture Best Practice:**
> Isolate the theme switcher logic (using `ThemeToggleService`, `ThemeCycleService`, or `ThemeSelectService`) in dedicated switcher components rather than injecting them directly into the root `AppComponent`.
>
> This keeps your root component clean, respects the single-responsibility principle, and ensures that theme-switching UI elements are highly reusable. Only inject the service at the root level if the root UI structure itself needs to dynamically react to theme changes (e.g., for dynamic logo assets or theme-dependent styles not covered by CSS variables).
```typescript
import { inject, Component } from '@angular/core';
import { ThemeToggleService } from 'ngx-theme-stack';
@Component({
selector: 'app-theme-toggle',
template: `
@if (theme.isHydrated()) {
} @else {
}
`,
})
export class ThemeToggle {
protected readonly theme = inject(ThemeToggleService);
}
```
---
## ๐ Advanced Guides & Documentation
For details on more advanced topics, check out the official guides:
- **[โ๏ธ Getting Started & Configuration](https://ngx-theme-stack-docs.wanderlee.site/guides/getting-started/)** - Detailed setup options and configuration properties.
- **[๐จ Styling & Custom Themes](https://ngx-theme-stack-docs.wanderlee.site/guides/styling/)** - Learn how to define CSS variables for custom themes.
- **[๐ช๏ธ Tailwind CSS v4 Integration](https://ngx-theme-stack-docs.wanderlee.site/guides/tailwind/)** - Map variables natively to Tailwind v4 theme configurations.
- **[โก Performance & Anti-Flash Strategies](https://ngx-theme-stack-docs.wanderlee.site/guides/performance/)** - Learn how the zero-flash system works and how to choose between `critters` and `blocking` modes.
- **[๐ค AI Agent Skill Setup](https://ngx-theme-stack-docs.wanderlee.site/guides/agent-integration/)** - Work with AI code assistants using the generated `SKILL.md` standard.
- **[๐ก๏ธ API Reference](https://ngx-theme-stack-docs.wanderlee.site/reference/api/)** - Deep dive into convenience services, methods, and `CoreThemeService` signals.
---
## ๐ค Contributing & Issues
Contributions are welcome! If you find a bug or have a suggestion, feel free to open an issue or submit a pull request:
- Report bugs or request features on [GitHub Issues](https://github.com/WanderleeDev/ngx-theme-stack/issues).
- For local development guidelines (how to build, test, and run the demo), please refer to the workspace [README](../../README.md).
---
## ๐ License
[MIT](https://github.com/WanderleeDev/ngx-theme-stack/blob/main/LICENSE)