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.