Custom components

Customization•4 min read||

You can extend DocsLit with your own Lit web components. Place a .js file in the components/ directory and it loads automatically alongside the built-in components.

Create a custom component

Create a file in components/ with your component definition:

class WcStatus extends LitElement {
  static properties = {
    type: { type: String }
  };

  static styles = css\`
    :host { display: inline-flex; align-items: center; gap: 6px; }
    .dot { width: 8px; height: 8px; border-radius: 50%; }
    .dot.up { background: #10b981; }
    .dot.down { background: #ef4444; }
    .dot.maintenance { background: #f59e0b; }
  \`;

  render() {
    return html\`
      <span class="dot \${this.type || 'up'}"></span>
      <slot></slot>
    \`;
  }
}
customElements.define('wc-status', WcStatus);

Reference the component in any page — no imports needed:

Service status: <wc-status type="up">Operational</wc-status>

Run docslit dev. The dev server loads custom components from components/ automatically and hot-reloads when you change them.

Component guidelines

DocsLit bundles Lit and makes `LitElement`, `html`, and `css` available globally. You do not need to import them in your component files.

Follow these conventions for custom components:

Prefix with wc- — All component tag names must start with wc- to work with the DocsLit rendering pipeline.
Use LitElement — Extend LitElement for shadow DOM encapsulation and reactive properties.
Register with customElements.define — Always define your element at the bottom of the file.
Keep components self-contained — Include styles within the component using static styles.

File structure

Each .js file can contain one or more component definitions. DocsLit concatenates all files in components/ into a single script and loads it after the built-in components.

Validation

The docslit validate command knows about custom components. It scans components/ for customElements.define calls and treats those tags as valid. Any <wc-*> tag that is not built-in or defined in components/ triggers a warning.

Build output

Custom components are included in both static and offline builds automatically. The components/ directory is copied to dist/components/ during the build.