igniteui-webcomponents/theming/theming-controller.d.ts

Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.

import { type ReactiveController, type ReactiveControllerHost, type ReactiveElement } from 'lit';
import type { Theme, Themes, ThemeVariant, ThemingControllerConfig } from './types.js';
/**
 * A reactive controller that manages theme adoption for a Lit host element.
 *
 * It resolves the active theme from one of two sources, in order of priority:
 *
 * 1. **Context** — provided by an ancestor `<igc-theme-provider>` element via the Lit context API.
 * 2. **Global** — the application-wide theme set via `configureTheme()`.
 *
 * When a context provider is present, the controller subscribes to its updates
 * and stops listening to global theme change events. When the host element is
 * disconnected and reconnected outside a provider, it automatically falls back
 * to the global theme.
 *
 * Theme styles are applied directly to the host's shadow root via `adoptStyles`
 * every time the active theme or variant changes.
 *
 * @example
 * Basic usage — typically created via {@link addThemingController}:
 * ```typescript
 * import { addThemingController } from '../../theming/theming-controller.js';
 * import { all } from './themes/themes.js';
 *
 * export default class IgcMyComponent extends LitElement {
 *   constructor() {
 *     super();
 *     addThemingController(this, all);
 *   }
 * }
 * ```
 *
 * @example
 * Accessing the current theme and variant at runtime:
 * ```typescript
 * export default class IgcMyComponent extends LitElement {
 *   private readonly _themes = addThemingController(this, all);
 *
 *   protected override render() {
 *     // Conditionally render based on active theme
 *     return this._themes.variant === 'dark'
 *       ? html`<div class="dark-layout"></div>`
 *       : html`<div class="light-layout"></div>`;
 *   }
 * }
 * ```
 */
declare class ThemingController implements ReactiveController {
    private readonly _host;
    private readonly _themes;
    private readonly _options?;
    private readonly _contextConsumer;
    private _theme;
    private _variant;
    private _themeSource;
    /** Gets the current theme. */
    get theme(): Theme;
    /** Gets the current theme variant. */
    get variant(): ThemeVariant;
    constructor(host: ReactiveControllerHost & ReactiveElement, themes: Themes, config?: ThemingControllerConfig);
    /** @internal */
    hostConnected(): void;
    /** @internal */
    hostDisconnected(): void;
    /** @internal */
    handleEvent(): void;
    private _applyContextTheme;
    private _applyGlobalTheme;
    private _applyTheme;
    private _adoptStyles;
}
/**
 * Creates and attaches a {@link ThemingController} to the given host element.
 *
 * This is the preferred way to add theming support to a component. The controller
 * is registered with the host's reactive controller lifecycle and automatically
 * resolves the active theme from an ancestor `<igc-theme-provider>` context or
 * falls back to the application-wide theme set via `configureTheme()`.
 *
 * @param host - The Lit element that will host the controller.
 * @param themes - The theme styles map containing `light` and `dark` variant entries,
 *   each keyed by theme name (`bootstrap`, `material`, `fluent`, `indigo`) and
 *   an optional `shared` entry applied regardless of theme.
 * @param config - Optional configuration.
 * @param config.themeChange - Callback invoked on the host whenever the active theme changes.
 *
 * @returns The created {@link ThemingController} instance.
 *
 * @example
 * Minimal setup in a component constructor:
 * ```typescript
 * import { addThemingController } from '../../theming/theming-controller.js';
 * import { all } from './themes/themes.js';
 *
 * export default class IgcMyComponent extends LitElement {
 *   constructor() {
 *     super();
 *     addThemingController(this, all);
 *   }
 * }
 * ```
 *
 * @example
 * With a `themeChange` callback and retained controller reference:
 * ```typescript
 * export default class IgcMyComponent extends LitElement {
 *   private readonly _themingController = addThemingController(this, all, {
 *     themeChange(theme) {
 *       // Called on `this` (the host) whenever the theme switches
 *       console.log(`Theme changed to: ${theme}`);
 *     },
 *   });
 *
 *   protected override render() {
 *     return html`<span>Current variant: ${this._themingController.variant}</span>`;
 *   }
 * }
 * ```
 */
export declare function addThemingController(host: ReactiveControllerHost & ReactiveElement, themes: Themes, config?: ThemingControllerConfig): ThemingController;
export type { ThemingController };