CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lit-element

A simple base class for creating fast, lightweight web components

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

css-styling.mddocs/

CSS Styling

Scoped CSS system with shadow DOM support, providing isolated styling and efficient style application. The CSS system enables component-scoped styles with optimal performance and shadow DOM integration.

Capabilities

CSS Template Function

Creates CSSResult objects for scoped component styling.

/**
 * Tagged template literal for creating CSS styles
 * @param strings Template literal strings
 * @param values Template literal values (CSSResult or number)
 * @returns CSSResult for component styling
 */
function css(
  strings: TemplateStringsArray, 
  ...values: (CSSResult | number)[]
): CSSResult;

/**
 * Class representing CSS text that can be used for styling
 */
class CSSResult {
  readonly cssText: string;
  readonly strings?: TemplateStringsArray;
  readonly values?: readonly CSSResult[];
  
  toString(): string;
}

Usage Examples:

import { LitElement, html, css } from "lit-element";

class MyElement extends LitElement {
  static styles = css`
    :host {
      display: block;
      padding: 16px;
      border: 1px solid #ccc;
      border-radius: 8px;
    }

    .header {
      font-size: 1.5em;
      font-weight: bold;
      margin-bottom: 16px;
      color: var(--header-color, #333);
    }

    .content {
      line-height: 1.6;
    }

    .button {
      background: #007bff;
      color: white;
      border: none;
      padding: 8px 16px;
      border-radius: 4px;
      cursor: pointer;
      transition: background 0.2s;
    }

    .button:hover {
      background: #0056b3;
    }

    .button:disabled {
      background: #ccc;
      cursor: not-allowed;
    }

    @media (max-width: 768px) {
      :host {
        padding: 8px;
      }
      
      .header {
        font-size: 1.2em;
      }
    }
  `;

  render() {
    return html`
      <div class="header">Component Title</div>
      <div class="content">
        <p>This content is styled with scoped CSS.</p>
        <button class="button">Click me</button>
      </div>
    `;
  }
}

Unsafe CSS

Creates CSSResult from untrusted CSS strings (use with caution).

/**
 * Creates a CSSResult from an untrusted CSS string
 * WARNING: Only use with trusted CSS content
 * @param value CSS string to wrap
 * @returns CSSResult for the CSS content
 */
function unsafeCSS(value: string): CSSResult;

Usage Examples:

import { LitElement, html, css, unsafeCSS } from "lit-element";

class MyElement extends LitElement {
  // Dynamic CSS from configuration
  static getStyles(theme: string) {
    const themeCSS = theme === "dark" 
      ? "background: #333; color: white;" 
      : "background: white; color: #333;";
    
    return css`
      :host {
        ${unsafeCSS(themeCSS)}
        padding: 16px;
      }
    `;
  }

  render() {
    return html`<p>Themed content</p>`;
  }
}

CSS Result Types

Type definitions for CSS results and groups.

/**
 * Single CSSResult or array of CSS results
 */
type CSSResultGroup = CSSResult | CSSResultArray;

/**
 * Array interface for multiple CSS results
 */
interface CSSResultArray extends Array<CSSResultGroup> {}

/**
 * CSSResult or native CSSStyleSheet
 */
type CSSResultOrNative = CSSResult | CSSStyleSheet;

Style Composition

Composing styles from multiple sources.

/**
 * Static styles property accepting single or multiple CSS results
 */
static styles: CSSResultGroup;

Usage Examples:

import { LitElement, html, css } from "lit-element";

// Base styles
const baseStyles = css`
  :host {
    display: block;
    font-family: sans-serif;
  }
`;

// Button styles
const buttonStyles = css`
  .btn {
    padding: 8px 16px;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  }

  .btn-primary {
    background: #007bff;
    color: white;
  }

  .btn-secondary {
    background: #6c757d;
    color: white;
  }
`;

// Layout styles
const layoutStyles = css`
  .container {
    max-width: 800px;
    margin: 0 auto;
    padding: 16px;
  }

  .grid {
    display: grid;
    gap: 16px;
  }
`;

class MyElement extends LitElement {
  // Compose multiple styles
  static styles = [baseStyles, buttonStyles, layoutStyles];

  render() {
    return html`
      <div class="container">
        <div class="grid">
          <button class="btn btn-primary">Primary</button>
          <button class="btn btn-secondary">Secondary</button>
        </div>
      </div>
    `;
  }
}

CSS Custom Properties

Using CSS custom properties (CSS variables) for theming.

/**
 * CSS custom properties for theming and customization
 */

Usage Examples:

import { LitElement, html, css } from "lit-element";

class MyElement extends LitElement {
  static styles = css`
    :host {
      --primary-color: #007bff;
      --secondary-color: #6c757d;
      --border-radius: 4px;
      --spacing: 16px;
      
      display: block;
      padding: var(--spacing);
    }

    .card {
      border: 1px solid var(--primary-color);
      border-radius: var(--border-radius);
      padding: var(--spacing);
      background: var(--card-background, white);
    }

    .title {
      color: var(--primary-color);
      font-size: var(--title-size, 1.5em);
      margin-bottom: calc(var(--spacing) / 2);
    }

    .button {
      background: var(--primary-color);
      color: var(--button-text-color, white);
      border: none;
      padding: calc(var(--spacing) / 2) var(--spacing);
      border-radius: var(--border-radius);
      cursor: pointer;
    }

    .button--secondary {
      background: var(--secondary-color);
    }
  `;

  render() {
    return html`
      <div class="card">
        <h2 class="title">Card Title</h2>
        <p>Card content goes here.</p>
        <button class="button">Primary</button>
        <button class="button button--secondary">Secondary</button>
      </div>
    `;
  }
}

// External theming
document.documentElement.style.setProperty('--primary-color', '#28a745');
document.documentElement.style.setProperty('--card-background', '#f8f9fa');

Style Utilities

Utility functions for working with styles.

/**
 * Apply styles to a shadow root or document
 * @param renderRoot Target element to apply styles to
 * @param styles CSS styles to apply
 */
function adoptStyles(renderRoot: ShadowRoot | Document, styles: CSSResultArray): void;

/**
 * Check if browser supports adoptedStyleSheets
 */
const supportsAdoptingStyleSheets: boolean;

/**
 * Get compatible style for cross-browser support
 * @param s CSSResult to make compatible
 * @returns CSSResult or CSSStyleSheet
 */
function getCompatibleStyle(s: CSSResult): CSSResultOrNative;

Host Styling

Styling the host element and responding to host states.

/**
 * :host selector for styling the component itself
 * :host() functional selector for conditional host styling
 * :host-context() for styling based on ancestor elements
 */

Usage Examples:

import { LitElement, html, css } from "lit-element";

class MyElement extends LitElement {
  static styles = css`
    /* Style the host element */
    :host {
      display: block;
      position: relative;
      padding: 16px;
      border: 1px solid #ccc;
    }

    /* Conditional host styling */
    :host([hidden]) {
      display: none !important;
    }

    :host([disabled]) {
      opacity: 0.5;
      pointer-events: none;
    }

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

    :host(.large) {
      padding: 32px;
      font-size: 1.2em;
    }

    /* Host context styling */
    :host-context(.mobile) {
      padding: 8px;
      font-size: 0.9em;
    }

    /* Host state styling */
    :host(:hover) {
      border-color: #007bff;
    }

    :host(:focus-within) {
      outline: 2px solid #007bff;
      outline-offset: 2px;
    }
  `;

  render() {
    return html`
      <div class="content">
        <p>This element can be styled from outside using host selectors.</p>
      </div>
    `;
  }
}

Shadow DOM Styling

Understanding shadow DOM style encapsulation.

/**
 * Shadow DOM provides style encapsulation
 * Styles inside shadow DOM don't affect external elements
 * External styles don't affect shadow DOM content (except through inheritance)
 */

Usage Examples:

import { LitElement, html, css } from "lit-element";

class MyElement extends LitElement {
  static styles = css`
    /* These styles are scoped to this component */
    p {
      color: blue;
      font-weight: bold;
    }

    .special {
      background: yellow;
      padding: 8px;
    }

    /* Slotted content styling */
    ::slotted(h1) {
      color: red;
      margin: 0;
    }

    ::slotted(.highlight) {
      background: lightblue;
    }
  `;

  render() {
    return html`
      <div>
        <p>This paragraph is styled by component CSS.</p>
        <div class="special">This has component-scoped styling.</div>
        <slot></slot>
      </div>
    `;
  }
}

// External styles won't affect the component's internal elements
// <style>p { color: red; }</style> won't change the component's <p> color

docs

core-element.md

css-styling.md

decorators.md

directives.md

index.md

polyfill-support.md

property-system.md

template-system.md

tile.json