Class StyleSheetResolve

Dynamically parses and indexes a CSSStyleSheet at runtime, exposing a selector-to-style mapping by individual selector parts. CSS variable resolution is also possible which enables the ability to flatten and resolve complex nested var(--...) chains defined across multiple selectors and layers.

When retrieving specific selector styles via StyleSheetResolve.get and StyleSheetResolve.getProperty it is possible to provide additional parent selectors that may define scoped CSS variables. These parent variable definitions will be substituted in the target selector data allowing specific element scoping of CSS variables to be flattened.

Current fallback support includes recursive var(--a, var(--b, ...)) chains with graceful partial substitution if some variables are undefined. This maintains correctness without introducing ambiguity or needing a complete AST based parser.

By default, when parsing CSSStyleSheet instances relative URL rewriting occurs converting url(...) references to absolute paths based on the CSSStyleSheet.href or the baseHref parse option for inline / synthetic CSSStyleSheets. You may turn off relative URL rewriting via setting the urlRewrite parse option to false.

By default, simple media queries / @media rules are parsed when all conditions are prefers-* features and the media query matches at runtime via window.matchMedia(...). Mixed conditions (IE with screen, width, etc.) are ignored by design. Only direct style rules under a media query are parsed. You may turn off media query parsing via setting the mediaQuery parse option to false.

The goal of this implementation is to realize a regex-based parser with small code size, minimal memory footprint, speed, and reasonable accuracy.

Core features:

  • Parses all or specific relevant @layer blocks.
  • Provides both direct and resolved access to styles via .get() and .getProperty().
  • Automatically rewrites relative URLs / url(...) references to absolute paths.

Parse Options:

  • Can set a base href for inline / synthetic CSSStyleSheets being processed via baseHref option.
  • Can filter out and exclude undesired CSS selector parts for parsing via excludeSelectorParts option.
  • Can filter out and include just desired CSS layers via includeCSSLayers option.
  • Can filter out and include just desired CSS selector parts via includeSelectorPartSet option.
  • Can disable relative URL rewriting by setting urlRewrite option to false.

Access Options:

  • Can return style property keys in camel case via camelCase option.
  • Can limit the depth of resolved CSS variables across parent-selector fallback chains via depth option.
  • Enables resolution of scoped CSS variables using a parent-selector fallback chain via resolve option.
  • Can enable cyclic dependency detection warnings when resolving CSS variables via warnCycles option.
  • Can enable warnings for non-existent parent-selector fallback lookup via warnResolve option.

Example

import { StyleSheetResolve } from '#runtime/util/dom/style';

// Parse first stylesheet in the browser `document`.
const parsedStyles = StyleSheetResolve.parse(document.styleSheets[0]);

// The `props` object has styles w/ CSS variables resolved from `input[type="text"]` for the dark theme.
const props = parsedStyles.get('input[type="text"]', { resolve: '.themed.theme-dark input' });
Implements
  • Iterable<[string, { [key: string]: string }]>

Constructors

constructor

Accessors

frozen size

Methods

[iterator] clear clone delete entries freeze get getProperty has keys merge parse set parse

Constructors

constructor

Accessors

frozen

  • get frozen(): boolean

  • Returns boolean

    Current frozen state; when true no more modifications are possible.

size

  • get size(): number

  • Returns number

    Returns the size / count of selector properties tracked.

Methods

[iterator]

  • "[iterator]"(): MapIterator<[string, { [key: string]: string }]>

  • Allows usage in for of loops directly.

    Returns MapIterator<[string, { [key: string]: string }]>

    Entries Map iterator.

clear

  • clear(): void

  • Clears any existing parsed styles.

    Returns void

clone

delete

  • delete(selector: string): boolean

  • Deletes an entry in the parsed stylesheet Map.

    Parameters

    • selector: string

      Selector key to delete.

    Returns boolean

    Success state.

entries

  • entries(): MapIterator<[string, { [key: string]: string }]>

  • Entries iterator of selector / style properties objects.

    Returns MapIterator<[string, { [key: string]: string }]>

    Tracked CSS selector key / value iterator.

    Yields

freeze

  • freeze(): void

  • Freezes this instance disallowing further modifications to the stylesheet data.

    Returns void

get

  • get(
        selector: string | Iterable<string>,
        options?: StyleSheetResolve.Options.Get,
    ): { [key: string]: string }

  • Gets all properties associated with the given selector(s). You may combine multiple selectors for a combined result. You may also provide additional selectors as the resolve option to substitute any CSS variables in the target selector(s).

    Parameters

    Returns { [key: string]: string }

    Style properties object or undefined.

getProperty

  • getProperty(
        selector: string | Iterable<string>,
        property: string,
        options?: StyleSheetResolve.Options.Get,
    ): string

  • Gets a specific property value from the given selector and property key.

    Parameters

    • selector: string | Iterable<string>

      A selector or list of selectors to retrieve.

    • property: string

      Specific property to locate.

    • Optionaloptions: StyleSheetResolve.Options.Get

      Options.

    Returns string

    Style property value.

has

  • has(selector: string): boolean

  • Test if StyleSheetResolve tracks the given selector.

    Parameters

    • selector: string

      CSS selector to check.

    Returns boolean

    StyleSheetResolve tracks the given selector.

keys

merge

  • merge(source: StyleSheetResolve, options?: Merge): this

  • Merges selectors and style properties from another StyleSheetResolve instance into this one. By default, the source of the merge overrides existing properties. You may choose to preserve existing values along with specifying exact selector matches.

    Parameters

    Returns this

    This instance.

parse

  • parse(
        styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>,
        options?: Parse,
    ): this

  • Clears existing stylesheet mapping and parses the given stylesheet or Map.

    Parameters

    • styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>

      The stylesheet element to parse or an existing parsed stylesheet Map.

    • Optionaloptions: Parse

      Options for parsing stylesheet.

    Returns this

    This instance.

set

  • set(selector: string, styleObj: { [key: string]: string }): void

  • Directly sets a selector key with the given style properties object.

    Parameters

    • selector: string

      A single selector key to set.

    • styleObj: { [key: string]: string }

      Style data object of property / value pairs.

    Returns void

Staticparse

  • parse(
        styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>,
        options?: Parse,
    ): StyleSheetResolve

  • Parse a CSSStyleSheet instance with the given options or accept a pre-filled Map generating a new StyleSheetResolve instance.

    Parameters

    • styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>

      The stylesheet instance to parse or an existing parsed stylesheet Map.

    • Optionaloptions: Parse

      Options for parsing stylesheet.

    Returns StyleSheetResolve

    New instance with the given parsed data.

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods