CSS :host Pseudo-Class

CSS :host Pseudo-Class

The CSS :host pseudo-class selects the shadow host of a web component from within its shadow tree. It allows a component to define styles for its own host element while keeping those styles inside the Shadow DOM.

:host Syntax

:host {
  property: value;
}

The :host pseudo-class does not accept arguments. It matches the shadow host associated with the shadow tree containing the stylesheet.

Example Syntax

:host {
  display: block;
  padding: 15px;
  border: 1px solid #ccc;
}

This rule gives the host element block-level display, padding, and a border.

Styling Internal Elements

:host {
  display: block;
}
.content {
  padding: 10px;
}

The :host selector styles the host element, while .content styles an element inside the shadow tree.

Where to Use :host

The selector is intended for stylesheets inside a shadow tree. It does not select arbitrary custom elements from a normal document stylesheet.

How :host Works

Shadow DOM allows a component to maintain an internal tree of elements and styles separate from the surrounding document.

The element to which the shadow root is attached is called the shadow host.

Shadow DOM Structure

<my-card></my-card>

JavaScript can attach a shadow root to the custom element.

const card = document.querySelector("my-card");
const shadow = card.attachShadow({ mode: "open" });

shadow.innerHTML = `
  <style>
    :host {
      display: block;
      border: 2px solid #0088cc;
    }
  </style>
  <p>Content inside the shadow tree.</p>
`;

The :host rule selects <my-card>, even though the stylesheet is located inside its shadow root.

Shadow Host vs. Shadow Root

The shadow host is the HTML element that owns the shadow root. The shadow root contains the component's internal elements and styles.

The :host pseudo-class selects the host element, not the shadow root itself.

Understanding the Shadow Host

A shadow host connects the component's external HTML element to its internal Shadow DOM.

Custom Element

<info-box></info-box>

In this example, <info-box> becomes the shadow host when a shadow root is attached to it.

Creating the Shadow Root

class InfoBox extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: "open" });
    shadow.innerHTML = "<p>Information goes here.</p>";
  }
}

customElements.define("info-box", InfoBox);

The custom element creates its shadow root when an instance is constructed.

Adding Host Styles

shadow.innerHTML = `
  <style>
    :host {
      display: block;
      background-color: #eaf6fc;
    }
  </style>
  <p>Information goes here.</p>
`;

This is an alternative to the preceding assignment. The :host rule styles the <info-box> element from inside its shadow tree.

Styling the Host

The :host pseudo-class is useful for establishing the default appearance of a web component.

Display Behavior

:host {
  display: block;
}

Custom elements are inline by default unless another style changes their display behavior. This rule makes the host behave as a block-level element.

Borders and Backgrounds

:host {
  display: block;
  padding: 15px;
  border: 1px solid #ccc;
  background-color: #f5f5f5;
}

These styles establish a default container appearance for the component.

Using CSS Custom Properties

:host {
  display: block;
  color: var(--component-text-color, #333);
  background-color: var(--component-bg-color, #f5f5f5);

}

CSS custom properties allow the surrounding document to configure component colors while preserving the internal stylesheet.

External Customization

my-card {
  --component-text-color: #003366;
  --component-bg-color: #eaf6fc;
}

This rule belongs in the document stylesheet. The values can be used by the component's internal :host styles.

:host vs. :host()

The :host and :host() pseudo-classes both select the shadow host, but the functional form adds a matching condition.

Comparison

Default Host Styles

:host {
  display: block;
  border: 1px solid #ccc;
}

Conditional Host Styles

:host(.featured) {
  border-color: #0088cc;
}

The functional form applies the border color only when the host has the featured class.

Use :host for default component styles and :host() for styles that depend on the host's classes, attributes, or states.

:host vs. :host-context()

The :host-context() pseudo-class is designed to match a host based on its surrounding document context. Unlike :host, it considers relationships outside the shadow tree.

Comparison

Context-Based Styling

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

This rule illustrates context-dependent styling. However, :host-context() has limited support and is deprecated in some browser documentation.

Preferred Alternative

For more predictable component customization, apply a class or attribute directly to the host and use :host().

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

:host Specificity

The :host pseudo-class has a specificity of 0-1-0. The functional form :host() also includes the specificity of its argument.

Specificity Examples

Important Cascade Difference

Even though :host has greater specificity than a simple element selector, ordinary styles applied to the host from the outer document take precedence over normal declarations from the shadow tree when they conflict.

This behavior is part of the Shadow DOM cascade and allows component users to customize host styles.

The CSS Cascade

Shadow DOM introduces an additional consideration when styles from the outer document and shadow tree apply to the same host element.

Internal Host Style

:host {
  color: #003366;
}

This rule belongs to the component's shadow stylesheet.

External Host Style

my-card {
  color: #cc3333;
}

This rule belongs to the surrounding document stylesheet.

Which Style Wins?

For normal declarations, the outer document's style takes precedence over the shadow tree's host style when the two conflict at the same cascade origin and importance.

For !important declarations, the ordering between the shadow tree and outer document is reversed.

Component Design

Use :host to establish sensible defaults and CSS custom properties to expose intended customization options.

Limitations

The :host pseudo-class is specifically designed for Shadow DOM and does not work as a general-purpose selector for custom elements.

Requires a Shadow Tree

The selector is meaningful within a shadow tree stylesheet. A normal document stylesheet cannot use :host to select arbitrary elements.

Does Not Select Internal Elements

The selector matches the host itself. Use ordinary selectors inside the shadow stylesheet to style internal elements.

Does Not Select Ancestors

The :host pseudo-class does not select the host's parent or other ancestors in the surrounding document.

External Style Overrides

Normal document styles can override normal shadow-tree host declarations. Consider this behavior when designing reusable components.

Accessibility

Web components should preserve accessible semantics, readable content, and keyboard interaction regardless of whether Shadow DOM is used.

Readable Component Styles

Use sufficient text contrast and appropriate spacing when defining host styles.

Keyboard Focus

If the host itself is interactive and keyboard-focusable, provide a visible focus indicator.

:host(:focus-visible) {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

This selector is appropriate for a host that can receive keyboard focus.

Semantic HTML

Use appropriate semantic elements inside the component. The :host pseudo-class changes styling but does not assign accessibility roles or keyboard behavior.

Best Practices

• Use :host to define default styles for a shadow host.
• Set an appropriate display value for custom elements.
• Use :host() when styling depends on host classes or attributes.
• Keep internal component styles inside the shadow tree.
• Use CSS custom properties for configurable component colors and other values.
• Remember that normal outer-document host styles can override normal shadow-tree host styles.
• Preserve accessible focus indicators and semantic HTML.
• Test components with and without external styling.

:host Example

This example creates a custom web component with styles inside its shadow root. The :host pseudo-class controls the component's outer border, background, padding, and display.

HTML

<my-info-box></my-info-box>

JavaScript

class MyInfoBox extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: "open" });
    shadow.innerHTML = `
      <style>
        :host {
          display: block;
          padding: 15px;
          border: 2px solid #0088cc;
          background-color: #eaf6fc;
          color: #003366;
        }
        h3 {
          margin: 0 0 8px;
          font-size: 1.125rem;
        }
        p {
          margin: 0;
        }
      </style>
      <h3>CSS :host Example</h3>
      <p>This component is styled from inside its Shadow DOM.</p>
    `;
  }
}

customElements.define("my-info-box", MyInfoBox);

Browser Result

Play in Editor

Note: The component's :host rule styles the <my-info-box> element, while the h3 and p rules style elements inside its shadow tree.

Browser Support

Baseline: Widely available. The :host pseudo-class is supported in modern versions of Chrome, Edge, Firefox, and Safari as part of Shadow DOM styling.

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

Specifications

The :host pseudo-class is defined in CSS Scoping Level 1. The specification describes how it matches the shadow host and interacts with the Shadow DOM styling model.

CSS Scoping Level 1 - :host