TS CSSVars

A type-safe way to define and use CSS variables in JS/TS context. With ts-cssvars you will not only forget about typos, but it also allows you to modularize and centralize your CSS variables. It's perfect for using with CSS-in-JS libraries like Styled Components and Emotion.

With Yarn:

yarn add ts-cssvars

With NPM:

npm i ts-cssvars

Using TS CssVars is very simple. The API contains the following:

• makeCssVars
• mergeCssVars

You can also check the complete 📚 API Reference for more details and documentation on all the type definitions.

With this function you can creates a CssVarContext object from a raw css variable definitions string. This context contains the cssvar(..) function used to reference the css variables from the context, the overwrite(..) function used to reassign the value of css variables in the context, and the definitions value which is the raw css variable definitions of the context. Keep in mind that the css variable must start with -- for the type system to work as expected.

const { cssvar, definitions, overwrite } = makeCssVars(`
  --gap: 5%;
  --nav-width: 500;
`);

const GlobalStyle = css`
  :root {
    ${definitions}

    @media screen and (min-width: 480px) {
      ${overwrite("gap", "1%")};
      ${overwrite("nav-width", 200)};
    }
  }

  nav > .container {
    padding: ${cssvar("gap")};
    width: ${cssvar("nav-width")}px;
  }
`;

In the example above, the cssvar(..) function arguments are typesafe, so trying to access a non-existing css variable will cause a compile time error:

cssvar("foo");
//     ^ Argument of type '"foo"' is not assignable to parameter of type '"gap" | "nav-width"'

Under the hood, the functions create raw strings that you can use on CSS to define and reference css variables:

cssvar("gap"); // var(--gap)
cssvar("nav-width"); // var(--nav-width)

overwrite("gap", "1%"); // --gap: 1%;
overwrite("nav-width", 500); // --nav-width: 500;

console.log(definitions);
// Output:
//   --gap: 5%;
//   --nav-width: 500;

You will usially want to create different CssVarContext object so you can modularize the variables. For example, you can create a context for your header, another for the foother, navigation, etc. Doing that will let you organize variables in a better way, and even use only the variables you need on specific files. But for some other cases you may want to use all the variables you creted in a single context.

The mergeCssVars(..) function allows you to merge two or more CssVarContext object into a single context. You may find this mostly usefull when theming, making things responsive, and when your global css variables are too big to handle on a single place (modularizing).

export const baseCssVars = makeCssVars(`
  --primary-color: red;
  --secondary-color: blue;
`);

 export const navCssVars = makeCssVars(`
  --gap: 5%;
  --nav-width: 500;
`);

export const mainCssVars = mergeCssVars(baseCssVars, navCssVars);

const { cssvar, definitions, overwrite } = mainCssVars;

const const GlobalStyle = css`
  :root {
    ${definitions}

    @media screen and (min-width: 480px) {
      ${overwrite("gap", "1%")};
      ${overwrite("nav-width", 200)};
    }
  }

  nav > .container {
    color: ${cssvar("primary-color")};
    padding: ${cssvar("gap")};
    width: ${cssvar("nav-width")}px;
  }
`;

Suggestions are always welcome! Please create an issue describing the request, feature, or bug. I'll try to look into it as soon as possible 🙂

Contributions are very welcome! To do so, please fork this repository and open a Pull Request against the main branch.

MIT License