meduzen/v-helper


A shorter SCSS access to CSS custom properties.

License: WTFPL

Language: CSS

Keywords: css, css-custom-properties, css-variables, sass, scss, scss-function


v.scss

v.scss brings a unique SCSS function that allows easier access to CSS custom properties using v(propName) instead of var(--propName).

Yup, v purpose is better readability by saving you 4 characters. It’s all it does.

Installation

  1. npm install v.scss pulls the package into your project.
  2. @import '~v.scss'; in a SCSS files make v() available.

Usage

Start by declaring some CSS custom properties:

:root {
  --primary: #000;
  --bg: #fff;
}

Then, access them with v().

html {
  background: v(bg);
  color: v(primary);
}

That’s it! Here’s the generated CSS:

html {
  background: var(--bg);
  color: var(--primary);
}

Fallback value as optional second parameter

The CSS var() function can take a fallback as second parameter: if the wanted custom property isn’t defined or valid for the browser, this parameter will be used.

In the following example, the background color will be #433221, the text will receive the yellow color and links the cyan one.

:root {
  --primary: cyan;
  --bg: #433221;
}

html {
  background: v(bg, brown); // `background: var(--bg, brown);`
  color: v(primaryyyy, yellow); // `color: var(--primaryyyy, yellow);`
}

a {
  color: v(primary); // color: var(--primary);
}

View it on CodePen.

Edge cases

SCSS interpolation

In the first example of this documentation, custom properties are assigned their final values:

:root {
  --primary: #000; // `#000` stays the same after compilation, it’s the final value
}

In order to use SCSS variables instead of final values, interpolation is required:

// all-my-variables.scss
$primary-color: #000;

// my-global-layout.scss
:root {
  --primary: $primary-color; // error 🚫, custom property assignment needs interpolation
  --primary: #{$primary-color}; // correct ✅, value interpolated with `#{}`
}

Interpolation means “Have a look at #{what is inside the curly braced} and replace the $value-string by its computed value ($000)”. In other words, --primary: #{$primary-color} is compiled to --primary: #000, as expected.

Assigning the computed value of a SCSS function follows the same interpolation rules. v() being a function, using it to assign the value of a CSS custom property to another custom property requires interpolation:

.my-class-that-erases-the-root-color {
  --superColor: var(--secondaryColor); // correct ✅, regular syntax
  --superColor: v(secondaryColor); // error 🚫, custom property assignment needs interpolation
  --superColor: #{v(secondaryColor)}; // correct ✅, function interpolated with `#{}`

  color: v(superColor); // correct ✅, `color` is not a custom property
}

In that case, as v()’s purpose is to increase readability and bring some coolness ✌️ in the assignment of CSS custom properties, one may favor sticking to the standard syntax (var(--propName)) instead of insulting v() by putting it in an even more uncool syntax (#{v(propName)}).

-- is a valid custom property name

It turns out that -- is a valid name for a CSS custom property.

Declaring and using it is all about edge cases:

.my-class-with-weird-declarations {
  --: .5; // error 🚫, expected "}", was "--: .5;"
  --#{''}: .5; // correct ✅
  #{'--'}: .5; // also correct ✅

  opacity: var(--); // error 🚫, Invalid CSS after "var(--": expected expression (e.g. 1px, bold), was ");"
  opacity: var(#{'--'}); // correct ✅
  opacity: v(); // correct ✅, thanks to v() coolness ✌️
}

Other example with three dashes instead of two dashes:

.my-class-with-more-dashes {
  --#{'-'}: .5; // correct ✅
  #{'---'}: .5; // also correct ✅

  opacity: var(#{'---'}); // correct ✅, interpolated
  opacity: v('-'); // correct ✅, thanks to v() coolness ✌️
}

Changelog

See releases.

See also

Project Statistics

Sourcerank 5
Repository Size 13.7 KB
Stars 7
Forks 0
Watchers 1
Open issues 0
Dependencies 0
Contributors 1
Tags 5
Created
Last updated
Last pushed

Top Contributors See all

Mehdi

Packages Referencing this Repo

v.scss
A SCSS v() function to shorten the writing of CSS custom properties (also named CSS variables).
Latest release 1.1.1 - Updated - 7 stars

Recent Tags See all

1.1.1 August 14, 2019
1.1.0 July 22, 2019
1.1.0 July 22, 2019
1.0.1 November 15, 2018
v1.0.0 November 15, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-08-14 23:31:04 UTC

Login to resync this repository