LightComponent

Overview

LightComponent is a base class that extends LitElement and renders directly to the light DOM instead of shadow DOM. Use this when you want your component to:

• Render content in the light DOM (no shadow DOM encapsulation)
• Allow global CSS to style component content
• Interact naturally with parent page styles
• Support natural children alongside rendered content

Components like PersistantCollapsible and ThemeSwitcher extend LightComponent.

Basic Usage

Create a custom component by extending LightComponent and implementing renderLightDom():

import LightComponent from './LightComponent.js';
import { html } from '../lit-all.min.js';

export default class MyLightComponent extends LightComponent {
  static properties = {
    message: { type: String }
  };

  constructor() {
    super();
    this.message = 'Hello';
  }

  renderLightDom() {
    return html`
      <div class="card p">
        <p>${this.message} from Light DOM!</p>
      </div>
    `;
  }
}

customElements.define('my-light-component', MyLightComponent);

Important: Always call super.updated() when overriding the updated() lifecycle method:

updated(changedProperties) {
  super.updated(); // Required!
  
  // Your custom logic here
  if(changedProperties.has('message')) {
    console.log('Message changed');
  }
}

When to Use

Use LightComponent when:

• You want global page styles to apply to your component
• You need to render alongside natural children
• Shadow DOM encapsulation would interfere with your component's purpose
• You're working with third-party libraries that expect light DOM

Use ShadowComponent instead when you need style encapsulation and scoped CSS.

Use HybridComponent when you need both shadow DOM styles and light DOM rendering.

JavaScript Reference

Constructor

Extends LitElement

new LightComponent()

Creates a new LightComponent instance that renders to the light DOM.

Requirements

• Lit (LitElement, html, render)

Properties

lightRoot: HTMLElement

A container element with display: contents that holds the rendered light DOM content. Created automatically by createRenderRoot().

Methods

createRenderRoot(): Element

Creates the light DOM render container instead of shadow DOM. This method:

• Creates a div with display: contents for layout transparency
• Appends it to the component as lightRoot
• Returns this instead of a shadow root

updated(): void

Called automatically by Lit when the component updates. Renders the result of renderLightDom() into lightRoot. Override this method if needed, but always call super.updated().

childrenUpdated(): void

A custom lifecycle callback that is automatically triggered whenever a child element is added or removed from the component. After this callback returns, requestUpdate() is automatically called to trigger a re-render.

Override this method to react to child changes:

export default class MyComponent extends LightComponent {
  childrenUpdated() {
    console.log('Children changed!');
    this.validateChildren();
  }
}

renderLightDom(): TemplateResult

Override this method to define what should be rendered to the light DOM. Returns an empty template by default. Use Lit's html tagged template literal to return your content.