CSS :host-context() Pseudo-Class

CSS :host-context() Pseudo-Class

The CSS :host-context() pseudo-class selects a Shadow DOM host based on whether the host or one of its ancestors matches a specified selector. It was designed to let web components respond to their surrounding document, but it is deprecated and has limited browser support.

:host-context() Syntax

:host-context(selector) {
  property: value;
}

The :host-context() pseudo-class accepts a compound selector. It matches the shadow host when that selector matches the host itself or an ancestor in the surrounding document.

Class Selector

:host-context(.dark) {
  color: #fff;
  background-color: #333;
}

This rule matches when the host or one of its ancestors has the dark class.

Attribute Selector

:host-context([data-theme="dark"]) {
  color: #fff;
  background-color: #333;
}

This rule checks for a matching data-theme attribute on the host or an ancestor.

Compound Selector

:host-context(.theme.dark) {
  border-color: #66ccff;
}

Both classes must be present on the same matching element.

Invalid Selector Argument

/* Invalid */
:host-context(.theme .dark) {
  color: #fff;
}

The argument cannot contain a descendant combinator. It must be a compound selector.

How :host-context() Works

Shadow DOM separates a web component's internal elements and styles from the surrounding document.

The :host-context() pseudo-class was introduced to let a shadow stylesheet respond to conditions outside the component.

Document Structure

<div class="dark">
  <my-card></my-card>
</div>

Shadow DOM Styles

:host {
  display: block;
  padding: 15px;
  background-color: #f5f5f5;
  color: #333;
}
:host-context(.dark) {
  background-color: #333;
  color: #fff;
}

In browsers implementing :host-context(), the second rule matches because an ancestor of <my-card> has the dark class.

Matching the Host

The selector can also match when the host itself satisfies the condition.

<my-card class="dark"></my-card>

However, when the condition is on the host itself, :host(.dark) is the preferred selector.

Ancestor Matching

The distinguishing feature of :host-context() is its ability to examine ancestors outside the shadow tree.

Direct Parent

<section class="dark">
  <my-card></my-card>
</section>

The component has a direct parent matching .dark.

Distant Ancestor

<main class="dark">
  <section>
    <div>
      <my-card></my-card>
    </div>
  </section>
</main>

The matching ancestor does not need to be the component's immediate parent.

Matching Rule

:host-context(.dark) {
  border: 2px solid #66ccff;
}

In supporting browsers, either document structure can cause this rule to match.

Not a Descendant Selector

The selector does not search for matching descendants inside the component. It examines the host and its ancestor context.

Context-Based Themes

One intended use of :host-context() was to allow components to respond automatically to a theme applied to a surrounding container.

Light Theme

:host {
  display: block;
  padding: 15px;
  background-color: #fff;
  color: #333;
}

Dark Theme

:host-context(.dark-theme) {
  background-color: #333;
  color: #fff;
}

HTML Example

<div class="dark-theme">
  <my-card></my-card>
</div>

The dark theme rule is intended to apply when the component is placed inside a matching container.

Modern Theme Handling

Because :host-context() is deprecated and not consistently supported, CSS custom properties are a more reliable approach for theme values that need to cross Shadow DOM boundaries.

Styling Internal Elements

The :host-context() pseudo-class can be combined with descendant selectors to style elements inside a shadow tree based on the surrounding context.

Internal Heading

:host-context(.dark) h3 {
  color: #fff;
}

This rule targets an internal heading when the host or an ancestor matches .dark.

Internal Content

:host-context(.dark) .content {
  background-color: #444;
  color: #fff;
}

This rule targets the internal .content element when the surrounding context matches.

Shadow DOM Boundary

The descendant selectors operate within the component's shadow tree. They do not select arbitrary elements outside the shadow tree.

Compatibility

These rules depend on browser support for :host-context(). They should not be the only method used to provide essential component styling.

:host-context() vs. :host()

Both pseudo-classes select the shadow host, but they examine different matching conditions.

Comparison

Host Class

:host(.dark) {
  background-color: #333;
}

This rule checks only the host's class.

Ancestor Class

:host-context(.dark) {
  background-color: #333;
}

This rule can also match an ancestor's class in supporting browsers.

For new components, prefer :host() and CSS custom properties over :host-context().

Recommended Alternatives

There are more compatible ways to make web components respond to themes and configuration settings.

CSS Custom Properties

Custom properties can inherit through the shadow boundary, making them useful for component themes.

Outer Document CSS

.dark-theme {
  --card-background: #333;
  --card-text: #fff;
}

Shadow DOM CSS

:host {
  display: block;
  padding: 15px;
  background-color: var(--card-background, #fff);
  color: var(--card-text, #333);
}

The component receives the custom property values through inheritance without using :host-context().

Host Attributes

<my-card theme="dark"></my-card>

:host([theme="dark"]) {
  background-color: #333;
  color: #fff;
}

This approach allows the component's theme to be configured directly on the host.

Choosing an Alternative

Use CSS custom properties for inherited design values. Use :host() when the component needs to respond to its own classes or attributes.

:host-context() Specificity

The :host-context() pseudo-class contributes a specificity of 0-1-0 plus the specificity of its argument.

Specificity Examples

Specificity and the Cascade

Specificity determines which matching declarations take precedence after higher-priority cascade factors have been considered.

For declarations applied directly to the shadow host, normal outer-document styles take precedence over normal shadow-tree host styles at the same origin.

Limitations

The :host-context() pseudo-class has important compatibility and maintenance limitations.

Deprecated Feature

The pseudo-class is deprecated. It is not recommended for new production websites or web components.

Limited Browser Support

Support is inconsistent across major browsers. Firefox, for example, does not provide general support for :host-context().

Shadow DOM Only

The selector is intended for use inside a shadow tree stylesheet. It does not work as a general-purpose selector in an ordinary document stylesheet.

Compound Selector Argument

The function accepts a compound selector rather than an arbitrary complex selector containing combinators.

Not Recommended for Essential Styling

Do not rely on :host-context() alone for text readability, theme contrast, or other essential visual behavior.

Accessibility

Context-dependent component styles must preserve readability and accessible interaction regardless of the surrounding theme.

Maintain Text Contrast

Ensure that light and dark themes provide sufficient contrast between text and background colors.

Avoid Unsupported Theme Dependencies

Because :host-context() is not consistently supported, use reliable alternatives when a component's readability depends on its theme.

Preserve Focus Indicators

Interactive components should retain visible keyboard focus indicators in every theme.

Do Not Rely on Color Alone

Use text, labels, or other accessible indicators to communicate important component states.

Best Practices

• Avoid :host-context() in new production code because it is deprecated.
• Understand that it checks the host and its ancestor context.
• Use :host() when a condition applies directly to the host.
• Use CSS custom properties for theme values inherited from surrounding containers.
• Provide compatible styles that do not depend on :host-context().
• Test components in browsers with and without support for the selector.
• Maintain readable colors and accessible focus indicators in every theme.

:host-context() Example

This example demonstrates how a web component can respond to a dark theme applied to an ancestor. It includes :host-context() for demonstration and CSS custom properties as a compatible alternative.

HTML

<div class="theme-container" id="theme-container">
  <my-theme-card></my-theme-card>
</div>
<button type="button" id="toggle-theme">Toggle Dark Theme</button>

CSS

.theme-container {
  --card-background: #f5f5f5;
  --card-text: #333;
  --card-border: #ccc;
}
.theme-container.dark-theme {
  --card-background: #333;
  --card-text: #fff;
  --card-border: #66ccff;
}

JavaScript

class MyThemeCard extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: "open" });
    shadow.innerHTML = `
      <style>
        :host {
          display: block;
          padding: 15px;
          border: 2px solid var(--card-border, #ccc);
          background-color: var(--card-background, #f5f5f5);
          color: var(--card-text, #333);
        }
        :host-context(.dark-theme) {
          border-style: dashed;
        }
        h3 {
          margin: 0 0 8px;
          font-size: 1.125rem;
        }
        p {
          margin: 0;
        }
      </style>
      <h3>CSS :host-context() Example</h3>
      <p>Toggle the surrounding theme.</p>
    `;
  }
}

customElements.define("my-theme-card", MyThemeCard);

document.getElementById("toggle-theme").addEventListener("click", () => {
  document.getElementById("theme-container").classList.toggle("dark-theme");
});

Browser Result

Play in Editor

Note: The background, text, and border colors change through inherited CSS custom properties in all supporting Shadow DOM browsers. The dashed border is controlled specifically by :host-context(.dark-theme) and appears only in browsers that implement the deprecated selector.

Browser Support

Baseline: Limited availability. The :host-context() pseudo-class is deprecated and is not supported consistently across major browsers. Avoid relying on it for new projects.

For current compatibility information, visit Can I Use? and search for :host-context.

Specifications

The :host-context() pseudo-class is described in CSS Scoping Level 1. It was designed to match a shadow host based on a compound selector matching the host or its ancestor context.

CSS Scoping Level 1 - :host-context()