{"id":13397982,"url":"https://github.com/shospodarets/css-vars","last_synced_at":"2025-08-21T12:30:35.274Z","repository":{"id":42233081,"uuid":"75545633","full_name":"shospodarets/css-vars","owner":"shospodarets","description":"Sass mixin to use CSS Custom Properties with Sass","archived":false,"fork":false,"pushed_at":"2023-03-04T02:46:04.000Z","size":601,"stargazers_count":181,"open_issues_count":3,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-08T06:42:42.836Z","etag":null,"topics":["css","css-custom-properties","css-variables","sass","sass-mixins","scss"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/css-vars","language":"JavaScript","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/shospodarets.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}},"created_at":"2016-12-04T15:22:37.000Z","updated_at":"2024-01-06T03:49:53.000Z","dependencies_parsed_at":"2024-01-18T10:22:35.378Z","dependency_job_id":"83b05790-40f9-4cd7-bef6-11527be8761e","html_url":"https://github.com/shospodarets/css-vars","commit_stats":null,"previous_names":["malyw/css-vars"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shospodarets%2Fcss-vars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shospodarets%2Fcss-vars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shospodarets%2Fcss-vars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shospodarets%2Fcss-vars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shospodarets","download_url":"https://codeload.github.com/shospodarets/css-vars/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230511479,"owners_count":18237657,"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-custom-properties","css-variables","sass","sass-mixins","scss"],"created_at":"2024-07-30T18:01:59.805Z","updated_at":"2024-12-19T23:14:41.257Z","avatar_url":"https://github.com/shospodarets.png","language":"JavaScript","readme":"# css-vars: Use CSS Custom Properties with Sass [![CircleCI](https://circleci.com/gh/malyw/css-vars.svg?style=svg)](https://circleci.com/gh/malyw/css-vars) [![TravisCI](https://travis-ci.org/malyw/css-vars.png)](https://travis-ci.org/malyw/css-vars)\n\n## Installation\n\n* With npm: `npm install css-vars`\n* With yarn: `yarn add css-vars`\n* Manually: get [this file](https://raw.githubusercontent.com/malyw/css-vars/master/css-vars.scss)\n\nInclude the main mixin file in your project using an `@import` statement:\n\n```scss\n@import \"[%PATH%]/css-vars/css-vars\";\n```\n\n## Usage\n\nTo declare variables, use `@include css-vars(\u003cmap of variables\u003e)`\n(you can reuse Sass variables):\n\n```scss\n// $css-vars-use-native: true;\n$white-color: #fff;\n$base-font-size: 10px;\n\n@include css-vars((\n        --main-color: #000,\n        --main-bg: $white-color,\n        --main-font-size: 1.5*$base-font-size,\n        --padding-top: calc(2vh + 20px)\n));\n```\n\nTo use variables, use the `var()` function:\n \n```scss\nbody {\n  color: var(--main-color);\n  background: var(--main-bg, #f00);\n  font-size: var(--main-font-size);\n  padding: var(--padding-top) 0 10px;\n}\n```\n\nBoth these syntaxes are taken from the\n[Custom Properties spec](https://drafts.csswg.org/css-variables/)\nwhich [is already implemented in most of the browsers](http://caniuse.com/#feat=css-variables).\n\n## CSS output\n\nThe default output from the above is:\n\n```css\nbody {\n  color: #000;\n  background: #fff;\n  font-size: 15px;\n  padding: calc(2vh + 20px) 0 10px;\n}\n\n```\n\nIf **`$css-vars-use-native: true;`** is uncommented, native CSS Custom Properties are used:\n\n```css\n:root {\n  --main-color: #000;\n  --main-bg: #fff;\n  --main-font-size: 15px;\n  --padding-top: calc(2vh + 20px);\n}\n\nbody {\n  color: var(--main-color);\n  background: var(--main-bg, #f00);\n  font-size: var(--main-font-size);\n  padding: var(--padding-top) 0 10px;\n}\n\n```\n\n## Declaration in selectors, reassigning variables\n\nVariables are declared on the global scope (`$css-vars` map for Sass, `root` for native CSS).\n\nYou can declare variables inside selectors\nand, of course, redefine any variable, e.g.:\n \n```scss\n// declaration outside of any selectors\n@include css-vars((\n  --line-height: 1,\n  --main-font-family: (Helvetica, Arial, sans-serif)\n));\n\nheader{\n  // declaration inside of a selector\n  @include css-vars((\n    --header-padding: 10px 20px,\n    --line-height: 1.428571429,\n    --border-color: rebeccapurple\n  ));\n  \n  padding: var(--header-padding);\n  line-height: var(--line-height); // 1.428571429 is applied\n  border: 1px solid var(--other-border-color);\n}\n```\n\n### Default values\n\n`var()` function takes the second param to assign the default value if a variable is not defined:\n\n```scss\na::after{\n  content: var(--external-link, \"external link\");\n  // \"external link\" is applied, as --external-link is not defined\n}\n```\n\n## Advantages of the mixin\n\nUsage of the mixin gives the useful debug information:\n\n- logs when a variable was not assigned but used\n- logs when some variable is reassigned\n- provides info when a variable is not defined, but there is a default value passed, which is used instead\n\nThis information is helpful in both cases for Sass and CSS variables.\n\nNone browsers so far provide such debug info for CSS custom properties.\n\nTo enable the mixin debug messages output during the Sass compilation, just add the following to your project:\n\n```scss\n$css-vars-debug-log: true;\n```\n\n## Trigger using of native CSS Custom Properties\n\nTo switch the mixin to use native CSS Custom Properties, just provide:\n\n```scss\n$css-vars-use-native: true;\n```\n\nIt's useful when:\n * You don't support [browsers without CSS Custom Properties](http://caniuse.com/#feat=css-variables)\n * To generate a separate CSS file which will be used for browsers which support them\n \nE.g.\n```js\n    const isSupported = window.CSS \u0026\u0026 window.CSS.supports \u0026\u0026\n    window.CSS.supports('--a', 0);\n    if(!isSupported){\n        removeCss('css-custom-properties.css');\n        loadCss('without-css-custom-properties.css');\n    }\n```\n\n## Caveats\n\nThere are some caveats, when CSS Custom Properties work in a different way.\n\nE.g. they cannot be used inside Media Query values,\nso the following code will work in Sass, but not in CSS (when you switch):\n\n```scss\n@include css-vars((\n        --tablet: 768px\n));\n\n@media screen and (min-width: var(--tablet)) {\n  body {\n    background: #ff0;\n  }\n}\n```\n\nAnother differences are regarding the different scopes for CSS and Sass variables.\n\nE.g. when you use assigned variable to define something in CSS and then reassign it- the used value will be updated.\nsass just inline values, so there will be no effect when you change a variable after.\n\nTo debug such cases when you switch just enable the debug messages:\n\n```scss\n$css-vars-debug-log: true;\n```\n \n## Limitations (**in case of Sass variables**)\n\nThere are some limitation because of the Sass nature:\n\n- mixin uses the global map to reassign variables,\nwhich may result in a different behavior from Custom Properties when non global variables are used.\n\n- Before passing a map of variables to the mixin, Sass invokes all the functions in it, together with var().\nAs result you cannot reuse variables in one declaration, e.g. this will not work:\n\n```scss\n@include css-vars((\n--link-color: #4183C4,\n--title-hover-color: var(--link-color)\n));\n```\n\nTo make it work, just split the declaration and the usage:\n\n```scss\n@include css-vars((\n--link-color: #4183C4,\n));\n\n@include css-vars((\n--title-hover-color: var(--link-color)\n));\n```\n\n- Sass doesn't invoke functions inside `calc()`, so in that case you have to trigger that using Sass interpolation `#{}`:\n\n```scss\n@include css-vars((\n  --link-indent: calc(#{var(--main-vertical-indent)} / 2)\n));\n.link{\n  width: calc(#{var(--btn-width)} * 2);\n  margin-bottom: var(--link-indent);\n}\n```\n\n# License\n\nMIT\n\n---\n\n![alt](https://static.hospodarets.com/img/blog/1482761911710817000.png)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshospodarets%2Fcss-vars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshospodarets%2Fcss-vars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshospodarets%2Fcss-vars/lists"}