angular/components · error · Error

mat-tab-group background color must be set through the Sass

Error message

mat-tab-group background color must be set through the Sass theming API

What it means

In dev mode (or when ENABLE_BACKGROUND_INPUT is false), MatTabGroup forbids setting the `backgroundColor` input because tab-group background theming is meant to go through the Sass theming API. The setter throws immediately instead of applying a `mat-background-*` class, so the palette-based background input is unsupported in this configuration.

Source

Thrown at src/material/tabs/tab-group.ts:251

  /**
   * Theme color of the background of the tab group. This API is supported in M2 themes only, it
   * has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/tabs/styling.
   *
   * For information on applying color variants in M3, see
   * https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
   *
   * @deprecated The background color should be customized through Sass theming APIs.
   * @breaking-change 20.0.0 Remove this input
   */
  @Input()
  get backgroundColor(): ThemePalette {
    return this._backgroundColor;
  }

  set backgroundColor(value: ThemePalette) {
    if (!ENABLE_BACKGROUND_INPUT) {
      throw new Error(`mat-tab-group background color must be set through the Sass theming API`);
    }

    const classList: DOMTokenList = this._elementRef.nativeElement.classList;

    classList.remove('mat-tabs-with-background', `mat-background-${this.backgroundColor}`);

    if (value) {
      classList.add('mat-tabs-with-background', `mat-background-${value}`);
    }

    this._backgroundColor = value;
  }

  private _backgroundColor!: ThemePalette;

  /** Aria label of the inner `tablist` of the group. */
  @Input('aria-label') ariaLabel!: string;

View on GitHub (pinned to 0411926e7d)

Solutions

1. Remove the backgroundColor binding from the <mat-tab-group> template
2. Apply the background via the Material Sass theming API (e.g. use mat.tabs-theme / mat-tab-group-custom-theme mixins, or the `mat-background-*` CSS class set by application styles)
3. Pin to an older Material version if the deprecated input is temporarily required

Example fix

// before
<mat-tab-group backgroundColor="primary">...</mat-tab-group>

// after
<mat-tab-group>...</mat-tab-group>
// plus, in styles.scss:
// @use '@angular/material' as mat;
// $theme: mat.define-theme(...);
// include mat.tabs-theme($theme) with background customization

// Before binding, avoid the input entirely; check the flag/source of truth
function usesDeprecatedTabBackground(group: MatTabGroup): boolean {
  return group.backgroundColor != null; // if set, the input is in play
}

function hasBackgroundColor(g: {backgroundColor?: ThemePalette}): g is {backgroundColor: ThemePalette} {
  return g.backgroundColor != null;
}

try {
  group.backgroundColor = 'primary';
} catch (e) {
  console.warn('backgroundColor input unsupported; use Sass theming API instead');
}

When it happens

Trigger: Binding `backgroundColor="primary"` (or `accent`/`warn`) on a `<mat-tab-group>` when the ENABLE_BACKGROUND_INPUT flag is disabled (i.e. the library version/build has removed the deprecated input).

Common situations: Upgrading Angular Material where the backgroundColor input was deprecated in favor of Sass theming; copying old template code from tutorials or migrated codebases that still bind the input.

Related errors

• A mat-tab-nav-panel must be specified via [tabPanel].
• No selected tab could be found.
• No active link could be found.
• Could not find tab matching filters: ${JSON.stringify(filter
• Cannot parse the specified color ${color}. Please verify it

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/f9c01c9fd6f82833. Report an issue: GitHub.