Skip to content

electrovir/lit-css-vars

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

lit-css-vars

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

Installation

npm i lit-css-vars

Usage

import {css} from 'lit';
import {defineCssVars} from 'lit-css-vars';

// css vars definition
export const myVars = defineCssVars({
    // key is CSS var name
    'my-var-name': 'blue', // value is the CSS var's default value
});

// usage
function renderStyles() {
    return css`
        p {
            /*
                This sets the CSS var's value to red. This works because ".name" is "--my-var-name".
            */
            ${myVars['my-var-name'].name}: red;
        }

        span {
            /*
                This shows how to use the CSS var's value. If a span is within a <p> element, color
                will be set to red. If not, the default value of blue (defined earlier) will be
                applied. This works because ".value" is "var(--my-var-name, blue)".
            */
            color: ${myVars['my-var-name'].value};
        }
    `;
}

Errors

If you see the following error messages in your types, read the explanations below on how to fix them.

Error: input CSS var names are too generic.

This happens if your input to createCssVars is too vague. This means that specific var names can't be extracted from the input object. This may happen if your input object has the vague key type of just string, like Record<string, string>. You need to make sure you use as const or somehow prevent TypeScript from broadening your input type.

import {wrapNarrowTypeWithTypeCheck} from '@augment-vir/common';
import {CssVarsSetup, defineCssVars} from 'lit-css-vars';

/**
 * This fails because assigning the object to type CssVarsSetup kills the specific 'my-var-name' key
 * name and instead assigns the object a generic CssVarName key (the key requirement for
 * CssVarsSetup).
 */
const BAD_VARS_SETUP_DO_NOT_USE: CssVarsSetup = {
    'my-var-name': 'blue',
};
// this errors because defineCssVars knows its input is too broad
// @ts-expect-error
export const BAD_VARS_DO_NOT_USE = defineCssVars(BAD_VARS_SETUP_DO_NOT_USE);

/**
 * This example works wonderfully because defineCssVars does not broaden the input type but still
 * holds it to a specific type requirement.
 */
export const myGoodVars = defineCssVars({
    'my-var-name': 'blue',
});

/**
 * This example works by using a helper function, wrapNarrowTypeWithTypeCheck, that requires the
 * input object to conform to the passed type (CssVarsSetup) without broadening the input type.
 * TypeScript thus knows that the exact key of goodVarsSetup is 'my-var-name' and all is well with
 * defineCssVars below.
 */
const goodVarsSetup = wrapNarrowTypeWithTypeCheck<CssVarsSetup>()({
    'my-var-name': 'blue',
});
export const myGoodVars2 = defineCssVars(goodVarsSetup);

Error: all CSS var names must be lower-kebab-case.

All CSS var name keys must be in lower-kebab-case:

import {defineCssVars} from 'lit-css-vars';

// expect errors because we're intentionally passing in invalid CSS var names as an example
// @ts-expect-error
export const myCssVars = defineCssVars({
    // good: kebab-lower-case
    'my-var-name': 'green',
    'my-var': 'green',
    // bad: has upper case letters
    'My-Var': 'red',
    // bad: not kebab case, must have at least one dash (-)
    thing: 'red',
});

About

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

Resources

License

MIT and 2 other licenses found

Licenses found

MIT
LICENSE
CC0-1.0
LICENSE-CC0
MIT
LICENSE-MIT

Stars

Watchers

Forks

Packages

No packages published