{"id":16321600,"url":"https://github.com/joselion/ts-cssvars","last_synced_at":"2025-05-14T09:14:35.239Z","repository":{"id":65189679,"uuid":"585819046","full_name":"JoseLion/ts-cssvars","owner":"JoseLion","description":"Safely define and use CSS vars on JS/TS context","archived":false,"fork":false,"pushed_at":"2024-06-24T05:05:53.000Z","size":4224,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-14T09:13:48.080Z","etag":null,"topics":["css","css-in-js","css-in-ts","cssvar","cssvariables","emotion","styled-components"],"latest_commit_sha":null,"homepage":"https://joselion.github.io/ts-cssvars/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoseLion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-06T06:47:17.000Z","updated_at":"2025-04-29T21:04:34.000Z","dependencies_parsed_at":"2024-06-24T04:47:33.599Z","dependency_job_id":"44d84a3a-3512-41a5-bc33-99ff9ded8b23","html_url":"https://github.com/JoseLion/ts-cssvars","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoseLion%2Fts-cssvars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoseLion%2Fts-cssvars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoseLion%2Fts-cssvars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoseLion%2Fts-cssvars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoseLion","download_url":"https://codeload.github.com/JoseLion/ts-cssvars/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110449,"owners_count":22016392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","css-in-js","css-in-ts","cssvar","cssvariables","emotion","styled-components"],"created_at":"2024-10-10T22:48:18.046Z","updated_at":"2025-05-14T09:14:35.185Z","avatar_url":"https://github.com/JoseLion.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/JoseLion/ts-cssvars/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseLion/ts-cssvars/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/JoseLion/ts-cssvars/actions/workflows/codeql.yml/badge.svg)](https://github.com/JoseLion/ts-cssvars/actions/workflows/codeql.yml)\n[![Pages](https://github.com/JoseLion/ts-cssvars/actions/workflows/pages.yml/badge.svg)](https://github.com/JoseLion/ts-cssvars/actions/workflows/pages.yml)\n[![Release](https://github.com/JoseLion/ts-cssvars/actions/workflows/release.yml/badge.svg)](https://github.com/JoseLion/ts-cssvars/actions/workflows/release.yml)\n[![NPM version](https://img.shields.io/npm/v/ts-cssvars?logo=npm)](https://www.npmjs.com/package/ts-cssvars)\n[![NPM bundle size](https://img.shields.io/bundlephobia/min/ts-cssvars)](https://www.npmjs.com/package/ts-cssvars)\n[![NPM downloads](https://img.shields.io/npm/dm/ts-cssvars)](https://www.npmjs.com/package/ts-cssvars)\n[![NPM license](https://img.shields.io/npm/l/ts-cssvars)](./LICENSE)\n[![GitHub Release Date](https://img.shields.io/github/release-date/JoseLion/ts-cssvars)](https://github.com/JoseLion/ts-cssvars/releases)\n[![Known Vulnerabilities](https://snyk.io/test/github/JoseLion/ts-cssvars/badge.svg)](https://snyk.io/test/github/JoseLion/ts-cssvars)\n\n# TS CSSVars\n\nA 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](https://styled-components.com/) and [Emotion](https://emotion.sh/docs/introduction).\n\n## Install\n\n**With Yarn:**\n\n```sh\nyarn add ts-cssvars\n```\n\n**With NPM:**\n\n```sh\nnpm i ts-cssvars\n```\n\n## Usage\n\nUsing TS CssVars is very simple. The API contains the following:\n\n- [makeCssVars](#makecssvars)\n- [mergeCssVars](#mergecssvars)\n\nYou can also check the complete [📚 API Reference](https://joselion.github.io/ts-cssvars/docs/build/) for more details and documentation on all the type definitions.\n\n### makeCssVars\n\nWith 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.\n\n```ts\nconst { cssvar, definitions, overwrite } = makeCssVars(`\n  --gap: 5%;\n  --nav-width: 500;\n`);\n\nconst GlobalStyle = css`\n  :root {\n    ${definitions}\n\n    @media screen and (min-width: 480px) {\n      ${overwrite(\"gap\", \"1%\")};\n      ${overwrite(\"nav-width\", 200)};\n    }\n  }\n\n  nav \u003e .container {\n    padding: ${cssvar(\"gap\")};\n    width: ${cssvar(\"nav-width\")}px;\n  }\n`;\n```\n\nIn the example above, the `cssvar(..)` function arguments are typesafe, so trying to access a non-existing css variable will cause a compile time error:\n\n```ts\ncssvar(\"foo\");\n//     ^ Argument of type '\"foo\"' is not assignable to parameter of type '\"gap\" | \"nav-width\"'\n```\n\nUnder the hood, the functions create raw strings that you can use on CSS to define and reference css variables:\n\n```ts\ncssvar(\"gap\"); // var(--gap)\ncssvar(\"nav-width\"); // var(--nav-width)\n\noverwrite(\"gap\", \"1%\"); // --gap: 1%;\noverwrite(\"nav-width\", 500); // --nav-width: 500;\n\nconsole.log(definitions);\n// Output:\n//   --gap: 5%;\n//   --nav-width: 500;\n``` \n\n### mergeCssVars\n\nYou 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.\n\nThe `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).\n\n```ts\nexport const baseCssVars = makeCssVars(`\n  --primary-color: red;\n  --secondary-color: blue;\n`);\n\n export const navCssVars = makeCssVars(`\n  --gap: 5%;\n  --nav-width: 500;\n`);\n\nexport const mainCssVars = mergeCssVars(baseCssVars, navCssVars);\n\nconst { cssvar, definitions, overwrite } = mainCssVars;\n\nconst const GlobalStyle = css`\n  :root {\n    ${definitions}\n\n    @media screen and (min-width: 480px) {\n      ${overwrite(\"gap\", \"1%\")};\n      ${overwrite(\"nav-width\", 200)};\n    }\n  }\n\n  nav \u003e .container {\n    color: ${cssvar(\"primary-color\")};\n    padding: ${cssvar(\"gap\")};\n    width: ${cssvar(\"nav-width\")}px;\n  }\n`;\n```\n\n## Something's missing?\n\nSuggestions are always welcome! Please create an [issue](https://github.com/JoseLion/ts-cssvars/issues/new) describing the request, feature, or bug. I'll try to look into it as soon as possible 🙂\n\n## Contributions\n\nContributions are very welcome! To do so, please fork this repository and open a Pull Request against the `main` branch.\n\n## License\n\n[MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoselion%2Fts-cssvars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoselion%2Fts-cssvars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoselion%2Fts-cssvars/lists"}