DEV Community: Dmitriy Mishchenko

Building a Modern Theme Switcher in Angular

Dmitriy Mishchenko — Sat, 29 Mar 2025 14:00:27 +0000

TL;DR: This guide shows how to build a modern theme switcher in Angular using Signals, CSS variables, and the new light-dark() function. We'll cover implementation details, best practices, and how to make it easily adoptable across your application.

In this guide, we'll explore how to implement a robust theme switching system in Angular that supports light, dark, and system themes. We'll cover the implementation details, best practices, and how to make it easily adoptable across your entire application.

💡 You can find the complete source code for this implementation on GitHub.

Prerequisites

Before diving into the implementation, make sure you have:

Angular 19+ installed
Basic understanding of Angular components and services
Familiarity with CSS variables and modern CSS features
Node.js 18+ and npm installed

Who this article is for

Angular developers looking to implement a robust theming system
Developers who want to support system theme preferences
Teams needing a maintainable and performant theme solution
Anyone interested in modern Angular and CSS features

Overview
Implementation Approach
CSS Variables and light-dark() Function
Theme Switcher Component
System Theme Integration
Component Adoption
Forcing Theme Sections
Best Practices
Common Pitfalls to Avoid
Testing and Browser Compatibility
Conclusion
Further Reading

Overview

A modern theme switcher should:

Support light and dark themes
Respect system preferences
Persist user choices
Be easy to maintain
Work seamlessly across components
Provide smooth transitions

Implementation Approach

Our implementation uses three key technologies:

Angular Signals for state management
CSS Variables for theme definition
The light-dark() CSS function for theme values

Why This Approach?

Signals: Provide reactive state management without complex state libraries
CSS Variables: Enable dynamic theme switching without JavaScript overhead
light-dark(): Simplifies theme value definition and maintenance

CSS Variables and light-dark() Function

The core of our theming system uses CSS variables with the light-dark() function:

:root {
  color-scheme: light dark;
  --accent: light-dark(#2337ff, #7c89ff);
  --black-raw: light-dark(rgb(15, 18, 25), rgb(255, 255, 255));
  --gray: light-dark(rgb(96, 115, 159), rgb(171, 178, 191));
  --background: light-dark(#fff, #1a1b26);
}

Benefits of this approach:

Single source of truth for color values
Automatic system theme support
Easy to maintain and update
No need for separate theme files

Theme Switcher Component

The theme switcher component manages theme state and user preferences:

export class ThemeSwitcherComponent implements OnInit, OnDestroy {
  // Track system theme preferences
  private readonly prefersColorScheme = window.matchMedia(
    "(prefers-color-scheme: dark)"
  );

  // Reactive state with signals
  protected readonly currentTheme = signal<Theme>(
    (localStorage.getItem("theme") as Theme) || "system"
  );

  // Computed theme value
  protected readonly effectiveTheme = computed(() => {
    if (this.currentTheme() === "system") {
      return this.prefersColorScheme.matches ? "dark" : "light";
    }
    return this.currentTheme();
  });
}

Key features:

Uses signals for reactive state
Persists preferences in localStorage
Computes effective theme based on system preference
Clean-up with OnDestroy

🎮 Try it out on Stackblitz:

System Theme Integration

System theme support is implemented at two levels:

CSS Level using prefers-color-scheme:

@media (prefers-color-scheme: dark) {
  /* Dark theme styles */
}

JavaScript Level using MediaQueryList:

window
  .matchMedia("(prefers-color-scheme: dark)")
  .addEventListener("change", (e) => {
    if (currentTheme === "system") {
      updateTheme("system");
    }
  });

Component Adoption

Components can easily adopt theming by using CSS variables:

.card {
  background: var(--background);
  color: var(--black-raw);
  border: 1px solid var(--gray-light);

  &:hover {
    border-color: var(--accent);
    box-shadow: var(--box-shadow);
  }
}

Benefits:

No component-specific theme logic needed
Automatic theme switching
Consistent look across the application
Easy to maintain and update

Forcing Theme Sections

While our theme switcher respects system preferences and user choices globally, sometimes you might need specific sections of your application to maintain a particular theme regardless of the global setting. The color-scheme property enables this functionality.

Basic Usage

<section class="dark-section">
  <h2>Always Dark Section</h2>
  <p>This section will remain dark regardless of system or user preferences.</p>
</section>

<section class="light-section">
  <h2>Always Light Section</h2>
  <p>
    This section will remain light regardless of system or user preferences.
  </p>
</section>

.dark-section {
  color-scheme: dark;
  // The light-dark() function will use the dark value here
  background: var(--background);
  color: var(--black-raw);
}

.light-section {
  color-scheme: light;
  // The light-dark() function will use the light value here
  background: var(--background);
  color: var(--black-raw);
}

Use Cases

This approach is particularly useful for:

Marketing sections that need consistent branding
Code snippets or documentation that should maintain readability
Media galleries with specific visual requirements
Third-party widget containers

Implementation Tips

Scope CSS Variables:

.themed-section {
  color-scheme: dark;

  // Override specific variables for this section
  --background: #1a1b26;
  --text-color: #ffffff;
}

Handle Nested Components:

@Component({
  selector: "app-themed-section",
  template: `
    <section [class]="forcedTheme">
      <ng-content></ng-content>
    </section>
  `,
  styles: [
    `
      .dark {
        color-scheme: dark;
      }
      .light {
        color-scheme: light;
      }
    `,
  ],
})
export class ThemedSectionComponent {
  forcedTheme: Signal<"dark" | "light"> = signal("dark");
}

Maintain Accessibility:

.themed-section {
  color-scheme: dark;

  // Ensure proper contrast even in forced theme
  --accent: #7c89ff; // Brighter accent for dark scheme

  // Add visual boundary for context
  border: 1px solid var(--gray-light);
  border-radius: 8px;
}

Best Practices for Forced Themes

Use Sparingly:

Only force themes when absolutely necessary
Consider the user's preference first
Document why a section needs a forced theme

Maintain Consistency:

Use the same CSS variables
Keep transitions smooth
Ensure proper contrast ratios

Handle Edge Cases:
- Test with system theme changes
- Verify nested themed sections
- Check interaction with global theme switches

Best Practices

Theme Definition:

Use semantic variable names (e.g., --background instead of --white)
Group related variables
Document color usage

Performance:

Use CSS Variables for dynamic values
Avoid JavaScript-based theme switching
Implement smooth transitions

Accessibility:

Ensure sufficient color contrast
Test with screen readers
Support reduced motion preferences

User Experience:
- Persist user preferences
- Provide smooth theme transitions
- Respect system preferences by default

Common Pitfalls to Avoid

Direct Color Usage:

   // ❌ Bad
   .element {
     color: #000;
   }

   // ✅ Good
   .element {
     color: var(--black-raw);
   }

Theme-Specific Styles:

   // ❌ Bad
   [data-theme="dark"] .element { ... }

   // ✅ Good
   .element { color: var(--text-color); }

Complex State Management:

   // ❌ Bad
   class ThemeService {
     private theme = new BehaviorSubject<Theme>('light');
   }

   // ✅ Good
   protected readonly currentTheme = signal<Theme>('system');

Testing and Browser Compatibility

Testing the Theme Switcher

To ensure your theme switcher works correctly across different scenarios:

Manual Testing:
- Test theme switching on different devices and browsers
- Verify system theme detection
- Check theme persistence after page reload
- Test forced theme sections
Accessibility Testing:
- Verify color contrast ratios meet WCAG guidelines
- Test with screen readers
- Check keyboard navigation
- Validate reduced motion support

Browser Compatibility

The light-dark() function is a modern CSS feature with the following browser support:

Chrome: 123+
Firefox: 120+
Safari: 17.5+
Edge: 123+

⚠️ Note: The light-dark() function is a relatively new feature. For older browsers, consider providing a fallback:

:root {
  /* Fallback for older browsers */
  --accent: #2337ff;

  /* Modern browsers */
  @supports (color: light-dark(#000, #fff)) {
    --accent: light-dark(#2337ff, #7c89ff);
  }
}

For broader browser support, you can also use the prefers-color-scheme media query as a fallback:

:root {
  /* Fallback using prefers-color-scheme */
  --accent: #2337ff;

  @media (prefers-color-scheme: dark) {
    --accent: #7c89ff;
  }

  /* Modern browsers with light-dark() */
  @supports (color: light-dark(#000, #fff)) {
    --accent: light-dark(#2337ff, #7c89ff);
  }
}

Conclusion

Building a theme switcher with Angular's modern features and CSS variables provides a maintainable, performant, and user-friendly solution. The combination of signals for state management and CSS variables for styling makes it easy to implement and adopt across your entire application.

Remember to:

Use CSS variables for theme values
Leverage the light-dark() function
Respect system preferences
Maintain accessibility
Keep the implementation simple

This approach scales well with application growth and provides a solid foundation for theme management in your Angular applications.

🔍 Want to explore the implementation in detail? Check out the complete source code on GitHub.

Next Steps

Implement the theme switcher in your application
Test with different devices and browsers
Consider adding more theme customization options
Share your implementation with the Angular community

Building your first generic Angular component

Dmitriy Mishchenko — Thu, 27 Mar 2025 12:28:45 +0000

TL;DR: Building generic components in Angular requires careful consideration of trade-offs. This guide covers when to build them, how to design them effectively, and best practices for implementation, testing, and maintenance.

Prerequisites

To get the most out of this article, you should have:

Basic understanding of Angular components and services
Familiarity with TypeScript generics
Experience building simple Angular applications

1. Introduction

Building generic, reusable components in Angular can be both rewarding and challenging. While they promise to reduce duplication and standardize interfaces across your application, they also come with significant complexity and maintenance considerations. This guide will help you decide whether creating a generic component is right for your situation, and if so, how to approach it effectively. We'll explore best practices, common pitfalls, and technical considerations to ensure your component serves its users well.

Who this article is for

Angular developers looking to build reusable component libraries
Team leads considering standardizing UI components across projects
Developers who find themselves duplicating similar components across an application
Anyone interested in modern Angular component architecture

2. Should You Build a Generic Component?

Before diving into implementation, consider these reasons why you might want to reconsider:

Resource constraints: It's time consuming and maybe you don't have enough capacity for this
Existing solutions: There are a lot of open source analogues that can be used; don't need to reinvent the wheel again. I suggest you make a proper research. It could save you a lot of effort.
Responsibility creep: Generic components often try to cover too many responsibilities at once. This happens when people blindly follow the DRY rule. It's better to split functionality into separate specific components. It's okay to repeat some code.

💡 Tip: Before starting, search for existing solutions on npm, GitHub, or popular UI libraries. You might find something that meets 80% of your needs with much less effort.

3. Planning and Management Considerations

If you decide to proceed with building a generic component, consider these organizational aspects:

Incremental development: Try to move faster in small increments; it helps to get more feedback and avoid getting stuck.
Support capacity: Discuss support capacity with your manager before committing to maintaining a shared component.
Feedback strategy: Try not to involve too many people in discussions at the beginning, as it will slow you down. Instead, gather feedback after release from your users (other developers).
Documentation and training: Be ready for repetitive questions from other developers. Plan for small training sessions - concepts that are obvious to you may not be to others who haven't worked extensively with the component.

4. Technical Implementation

API Design and Type Safety

Clear public API: Your public API should be extremely clear for your users. Stick to naming conventions for inputs and outputs. Better to rely on what Angular and popular libraries already provide.
Type definitions: Cover your generic component with types and interfaces. It should be clear what type each input expects and what type each output event has.
Backward compatibility: At some point after your component is in use, you need to preserve the existing contract. Changes should happen only inside your component while the contract remains the same. You can ignore this during the MVP phase, but if you need to apply breaking changes, consider migration scripts or schematics.

Modern Angular Features

Signals: Utilize the latest stable Angular features like Signals, especially computed signals inside your component. Angular signals provide simple reactivity in your template. With computed signals, you can transform input data without contract changes.
Content projection: This is an underestimated feature. Allow your users to choose what to project inside your component, making it more flexible to changes.

A generic data table component example

// First, define our interfaces
export interface TableColumn<T = any> {
  key: keyof T;
  header: string;
  cellTemplate?: TemplateRef<unknown>;
  sortable?: boolean;
  width?: string;
}

export type TableSorting = "asc" | "desc";

// data-table.component.ts
import {
  Component,
  input,
  output,
  model,
  computed,
  contentChild,
  TemplateRef,
  ChangeDetectionStrategy,
} from "@angular/core";
import { NgTemplateOutlet } from "@angular/common";
import { GetCellValuePipe } from "./get-cell-value.pipe";
import { GetSortIconPipe } from "./get-sort-icon.pipe";

@Component({
  selector: "app-data-table",
  templateUrl: "./data-table.component.html",
  changeDetection: ChangeDetectionStrategy.OnPush,
  standalone: true,
  imports: [NgTemplateOutlet, GetCellValuePipe, GetSortIconPipe],
})
export class DataTableComponent<T = any> {
  // Events
  readonly rowClick = output<T>();

  // Input signals for reactive state management
  readonly data = input.required<T[]>();
  readonly columns = input.required<TableColumn<T>[]>();

  // Model signals for two-way binding
  readonly sortColumn = model<string | null>(null);
  readonly sortDirection = model<TableSorting>("asc");

  // Public API with computed signals
  readonly displayData = computed(() => {
    const data = [...this.data()];
    const sortCol = this.sortColumn();

    if (sortCol) {
      return data.sort((a: any, b: any) => {
        const aValue = a[sortCol];
        const bValue = b[sortCol];

        if (aValue === bValue) return 0;

        const comparison = aValue > bValue ? 1 : -1;
        return this.sortDirection() === "asc" ? comparison : -comparison;
      });
    }

    return data;
  });

  // Content projection for custom templates
  protected readonly headerTemplate =
    contentChild<TemplateRef<unknown>>("headerTemplate");
  protected readonly footerTemplate =
    contentChild<TemplateRef<unknown>>("footerTemplate");

  // Public methods
  protected sort(column: TableColumn<T>): void {
    if (!column.sortable) return;

    const key = column.key as string;

    if (this.sortColumn() === key) {
      // Toggle direction if already sorting by this column
      this.sortDirection.set(this.sortDirection() === "asc" ? "desc" : "asc");
    } else {
      // Set new sort column and reset direction
      this.sortColumn.set(key);
      this.sortDirection.set("asc");
    }
  }

  protected onRowClick(item: T): void {
    this.rowClick.emit(item);
  }
}

<div class="table-container">
  <!-- Custom header template or default header -->
  @if (headerTemplate(); as headerTemplate) {
  <ng-container [ngTemplateOutlet]="headerTemplate"></ng-container>
  } @else {
  <div class="table-header">
    <h3>Data Table</h3>
  </div>
  }

  <!-- Table -->
  <table>
    <thead>
      <tr>
        @for (column of columns(); track column.key) {
        <th
          [style.width]="column.width"
          [class.sortable]="column.sortable"
          (click)="sort(column)"
        >
          {{ column.header }} @if (column.sortable) {
          <span class="sort-icon"
            >{{ column | getSortIcon : sortColumn() : sortDirection() }}</span
          >
          }
        </th>
        }
      </tr>
    </thead>
    <tbody>
      @for (item of displayData(); track item) {
      <tr (click)="onRowClick(item)">
        @for (column of columns(); track column.key) {
        <td>
          <!-- Custom cell template or default cell -->
          @if (column.cellTemplate) {
          <ng-container
            [ngTemplateOutlet]="column.cellTemplate"
            [ngTemplateOutletContext]="{ $implicit: item, column: column }"
          >
          </ng-container>
          } @else { {{ item | getCellValue : column.key }} }
        </td>
        }
      </tr>
      }
    </tbody>
  </table>

  <!-- Custom footer template -->
  @if (footerTemplate(); as footerTemplate) {
  <ng-container [ngTemplateOutlet]="footerTemplate"></ng-container>
  }
</div>

Usage Example

// users-page.component.ts
import {
  ChangeDetectionStrategy,
  Component,
  computed,
  Signal,
  TemplateRef,
  viewChild,
} from "@angular/core";
import {
  DataTableComponent,
  TableColumn,
} from "../data-table/data-table.component";

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
  active: boolean;
}

@Component({
  selector: "app-users-page",
  templateUrl: "./users-page.component.html",
  styleUrl: "./users-page.component.css",
  changeDetection: ChangeDetectionStrategy.OnPush,
  standalone: true,
  imports: [DataTableComponent],
})
export class UsersPageComponent {
  protected readonly activeTemplate =
    viewChild<TemplateRef<unknown>>("activeTemplate");

  users: User[] = [
    {
      id: 1,
      name: "John Doe",
      email: "john@example.com",
      role: "Admin",
      active: true,
    },
    {
      id: 2,
      name: "Jane Smith",
      email: "jane@example.com",
      role: "User",
      active: false,
    },
    // More users...
  ];

  columns: Signal<TableColumn<User>[]> = computed(() => {
    const activeTemplate = this.activeTemplate();
    return [
      { key: "name", header: "Name", sortable: true },
      { key: "email", header: "Email", sortable: true },
      { key: "role", header: "Role", sortable: true },
      {
        key: "active",
        header: "Status",
        sortable: true,
        cellTemplate: activeTemplate,
      },
    ];
  });

  onUserClick(user: User): void {
    console.log("User clicked:", user);
    // Handle user selection
  }

  addUser(): void {
    // Handle adding a new user
  }
}

<!-- users-page.component.html -->
<app-data-table
  [data]="users"
  [columns]="columns()"
  (rowClick)="onUserClick($event)"
>
  <ng-template #headerTemplate>
    <div class="custom-header">
      <h2>User Management</h2>
      <button (click)="addUser()">Add User</button>
    </div>
  </ng-template>
</app-data-table>
<ng-template #activeTemplate let-user>
  <span class="status-indicator" [class.active]="user.active">
    {{ user.active ? 'Active' : 'Inactive' }}
  </span>
</ng-template>

This example demonstrates several modern Angular features:

Input/Output Signals: Using input() and output() functions instead of decorators for reactive inputs and outputs
Model Signals: Using model() for two-way binding with the sortColumn and sortDirection
New Control Flow Syntax: Using @if, @else, and @for instead of structural directives like *ngIf and *ngFor
Content Projection: Using contentChild and ng-template for flexible content customization
OnPush Change Detection: For optimal performance
Computed Signals: For derived state like sorted data

These features make the component more reactive, type-safe, and maintainable while improving performance.

Same example on the Stackblitz

Performance and Optimization

⚠️ Important: Change detection strategy should be OnPush for all generic components. This is non-negotiable for performance reasons.

Large datasets: Consider optimizations if your component will be used with large data sets. For tables, implement virtual scrolling (can be configurable via input).
Memoization: Use memoization techniques for expensive operations. For simpler cases, computed signals can handle this for you.
State management: Don't abuse state as it will create difficulties in controlling your component. If you need state providers, separate them from other parts of your app. The same applies to localStorage or other storage - use separate keys to avoid conflicts.

Testing and Quality Assurance

Unit tests: Cover your code with tests - at minimum, unit tests should verify how your component reacts to all inputs and confirm it emits all expected events/outputs.
E2E tests: If you have capacity, write basic E2E tests for main scenarios. For a table component, cover pagination, sorting, and search actions to ensure all core functionality works properly after changes.
Cross-browser compatibility: Try to cover all main browsers and devices if you have capacity. The "we only use Chrome" approach rarely lasts long.
Fallbacks: If you have browser/device support limitations, discuss this with management. Either mark certain devices/browsers as not well supported, or disable component usage in those environments (though this is not ideal).

🧪 Testing tip: Create a comprehensive test suite early. It will save you time when refactoring and give you confidence when making changes.

User Experience Considerations

Internationalization (i18n): Consider what types of users will interact with your component. Plan for date/number formatting, RTL support, and text translation.
Styling and theming: Make styling configurable. CSS custom properties are one of the best solutions to let developers change appearance aspects.
Accessibility: Accessibility should never be an afterthought. Ensure your component follows WCAG guidelines by implementing proper keyboard navigation (tab order, focus management), adding appropriate ARIA attributes (roles, labels, descriptions), and maintaining sufficient color contrast. Test with screen readers like NVDA or VoiceOver. Remember that accessibility benefits all users, not just those with disabilities. For interactive components like tables, dropdowns, or modals, implement proper keyboard controls (arrow keys, Escape key) and ensure focus trapping when necessary. Document accessibility features so developers using your component understand how to maintain them.

5. Documentation and Sharing

Demo page: Create a demo page with configurable options, or a playground page hidden behind a dev flag that you can share with other developers.
Change communication: Learn how to publish changes clearly so users are informed. Write changelogs, update your demo page/playground, and provide code examples.

📝 Documentation tip: Include both API documentation and usage examples. Show common patterns and edge cases to help developers understand how to use your component effectively.

6. Common Pitfalls to Avoid

Over-generalization: Making components too generic often leads to complexity and maintenance issues. Focus on solving specific problems rather than creating a component that tries to do everything.
Poor documentation: Generic components without clear documentation become unusable. Document not just the API, but also usage patterns, edge cases, and limitations.
Ignoring performance: Generic components that don't consider performance can cause application-wide slowdowns. Always use OnPush change detection and consider the impact of your component on the overall application performance.
Tight coupling: Avoid dependencies on specific services or state management solutions. Your component should work regardless of the application architecture it's used in.

7. Conclusion

Building a generic component requires careful planning, solid technical implementation, and ongoing maintenance. When done right, it can significantly improve development efficiency and application consistency. However, always weigh the benefits against the costs before embarking on this journey.

Next Steps

Start small with a simple generic component that solves a specific problem
Join Angular communities to share your components and get feedback
Consider contributing to open-source component libraries to learn from others

DEV Community: Dmitriy Mishchenko

Building a Modern Theme Switcher in Angular

Prerequisites

Who this article is for

Table of Contents

Overview

Implementation Approach

Why This Approach?

CSS Variables and light-dark() Function

Theme Switcher Component

System Theme Integration

Component Adoption

Forcing Theme Sections

Basic Usage

Use Cases

Implementation Tips

Best Practices for Forced Themes

Best Practices

Common Pitfalls to Avoid

Testing and Browser Compatibility

Testing the Theme Switcher

Browser Compatibility

Conclusion

Next Steps

Further Reading

Building your first generic Angular component

Prerequisites

1. Introduction

Who this article is for

2. Should You Build a Generic Component?

3. Planning and Management Considerations

4. Technical Implementation

API Design and Type Safety

Modern Angular Features

Usage Example

Same example on the Stackblitz

Performance and Optimization

Testing and Quality Assurance

User Experience Considerations

5. Documentation and Sharing

6. Common Pitfalls to Avoid

7. Conclusion

Next Steps

Further Reading