Configuration

Learn how to configure theme switching, icons registry, zoneless change detection, and SSR hydration safety.

Application Setup

BeigeUI components are fully standalone with ChangeDetectionStrategy.OnPush. No root module is required:

src/app/app.config.tstypescript

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideBeTheme } from '@saarcmaststech/beige-ui';
import { appRoutes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(appRoutes),
    // Applies the persisted theme during app init (avoids a flash).
    provideBeTheme({
      mode: 'system',              // 'light' | 'dark' | 'system'
      palette: 'beige',            // preset id, or { base: '#3b82f6' }
      radius: 'default',           // 'sharp' | 'compact' | 'default' | 'relaxed' | 'pill'
      density: 'comfortable',      // 'compact' | 'comfortable' | 'spacious'
      storageKey: 'my-app-theme'   // null disables localStorage persistence
    })
  ]
};

Dark Mode & Theme Switching

BeigeUI ships an injectable BeThemeService. It writes the design tokens onto the root <html> element, resolves 'system' against prefers-color-scheme (and keeps tracking OS changes), and persists the choice to localStorage. Every DOM and storage access is guarded for SSR.

src/app/theme-toggle.component.tstypescript

import { Component, inject } from '@angular/core';
import { BeThemeService } from '@saarcmaststech/beige-ui';

@Component({
  selector: 'app-theme-toggle',
  standalone: true,
  template: `
    <button (click)="theme.toggle()">
      {{ theme.isDark() ? 'Light' : 'Dark' }} mode
    </button>
  `
})
export class ThemeToggleComponent {
  readonly theme = inject(BeThemeService);

  // theme.setMode('system')  -> follows prefers-color-scheme (live)
  // theme.isDark()           -> resolved boolean signal
  // Toggling sets [data-theme="dark"] on <html> and persists to localStorage.
}

Brand Palette, Radius & Density

The same service drives runtime theming: apply a built-in preset, generate a full palette from a single brand hex, or switch the global corner-radius and spacing-density scales. Use provideBeThemeConfig() for defaults without eager initialization.

src/app/theme.tstypescript

import { inject } from '@angular/core';
import { BeThemeService } from '@saarcmaststech/beige-ui';

const theme = inject(BeThemeService);

// 1. A built-in brand preset
theme.setPalette('ocean');

// 2. Any brand hex — the --beige-400/500/600 ramp and the
//    --beige-color-primary* states are generated via color-mix()
theme.setBrandColor('#7c3aed');

// 3. Global shape + spacing scale (remaps --beige-radius-* / --beige-spacing-*)
theme.setRadius('relaxed');
theme.setDensity('compact');

// Copy the resulting token block for a static stylesheet:
console.log(theme.generatedCss());

Icon Registry Setup

BeigeUI provides built-in feather/lucide icons and an injectable BeIconRegistry service to register custom SVGs:

src/app/app.tstypescript

import { inject } from '@angular/core';
import { BeIconRegistry } from '@saarcmaststech/beige-ui';

export class App {
  private readonly iconRegistry = inject(BeIconRegistry);

  constructor() {
    // Register custom SVGs or extend existing icons
    this.iconRegistry.registerIcon('custom-star', '<svg>...</svg>');
  }
}

SSR & Hydration Safety

All BeigeUI components avoid direct browser global access (e.g. window, document) during initialization. Overlays and DOM measurements are executed through afterNextRender() or guarded with isPlatformBrowser() for seamless Angular Server-Side Rendering (SSR).