lit-css-vars/dist/setters-and-getters.d.ts

For easily creating and sharing typed CSS vars for the lit.dev ecosystem.

import { type CssVarName, type SingleCssVarDefinition } from './define-css-vars.js';
/**
 * Set the given CSS var to the given value on the given element. Allows numeric values but converts
 * them to strings (since the style.setProperty API only allows strings).
 *
 * @category Main
 */
export declare function setCssVarValue({ onElement, toValue, forCssVar, }: {
    onElement: HTMLElement;
    toValue: string | number;
    forCssVar: SingleCssVarDefinition;
}): void;
/**
 * Set the given property's value to the given CSS var on the given element, using
 * "element.style.setProperty".
 *
 * Note: this is a slow operation. Do not run this for many CSS vars at once. Instead, prefer
 * {@link applyCssVarsViaStyleElement} for bulk CSS var setting.
 *
 * @category Main
 */
export declare function applyCssVar({ onElement, forProperty, toCssVar, }: {
    onElement: HTMLElement;
    forProperty: string;
    toCssVar: SingleCssVarDefinition;
}): void;
/**
 * Create the global `<style>` element used by {@link applyCssVarsViaStyleElement} to set many CSS
 * var values at once.
 *
 * @category Internal
 */
export declare function createCssVarStyleElement(
/** The id for the `<style>` element. This should, ideally, be a kebab-case string. */
styleKey: string, 
/**
 * Customize where the `<style>` element is attached.
 *
 * @default document.head
 */
context?: Element): HTMLStyleElement;
/**
 * Efficiently sets many CSS var values via a `<style>` element.
 *
 * @category Main
 * @returns The created or existing `<style>` element in case you wish to reuse it.
 */
export declare function applyCssVarsViaStyleElement(
/**
 * The CSS Var values to apply. The keys of this object are the CSS Var names and they will be
 * set to the given values. `undefined` values will not be omitted (not set). The keys may
 * include or omit the CSS required `'--'` prefix.
 */
cssVarValues: Record<CssVarName, string | number | undefined>, 
/** The id for the `<style>` element. This should, ideally, be a kebab-case string. */
styleKey: string, 
/**
 * Customize where the `<style>` element is attached.
 *
 * @default document.head
 */
context?: Element): HTMLStyleElement;
/**
 * Read the given CSS var's value on the given element. If "includeCascade" is set to true, the
 * given elements styles are computed to retrieve cascaded CSS var values. If "includeCascade" is
 * false, the CSS var is read directly off the element, which will only read values from the element
 * on which the CSS var was directly set.
 *
 * WARNING: "includeCascade: true" is less performant because it runs "globalThis.getComputedStyle".
 * However, in practice I've yet to actually see this be an issue (unless you're running this in an
 * immediate infinite loop but of course don't do that).
 *
 * @category Main
 */
export declare function readCssVarValue({ onElement, forCssVar, includeCascade, }: {
    onElement: HTMLElement;
    forCssVar: SingleCssVarDefinition;
    includeCascade?: boolean;
}): string;