The vary mixin is the most flexible, scalable and modular Sass theming solution out there.

Quick start

Compatible with Sass 3.4+ and libsass 3.2+, vary covers every aspect of CSS theming, from using body classes to BEM modifiers and all in between, solving lots of consistency and maintenance issues.

But let's see how this works. The most common theming pattern is using a .is-foo body class, where foo is the entity for which the CSS variations are destinated to (e.g. user, admin). Each of these entities will have a different styling.

Body class example

$vary-map: (
  user: (
    'color-primary': blue,
    'border': '1px solid #ff0'
  ),
  admin: (
    'color-primary': pink,
    'border': '10px solid black'
  )
);

.foo{
	background: red;

	@include vary($create: parent) {
		background: vary-get('color-primary');
		border: vary-get('border');
	}
}

.foo{
	background: red;	
}

.is-user .foo{
	background: blue;
	border: 1px solid #ff0;
}

.is-admin .foo{
	background: pink;
	border: 10px solid red;
}

In order to relate the values with the entities, vary uses Sass maps. Build your $vary-map and you can start creating variations of any selector.

Withing the vary scope, you can request values like the primary color with vary-get. Then vary will loop through the entities in the map and create whatever has been specified for you (in this case a body class) per entity, each with the corresponding primary color and border.

Keeping the entity names in a single place across the codebase helps with consistency and scalability. If you ever need to create another variation, just add the values to the map and it will replicate accross the entire CSS.

What else?

vary is very powerful and full of possibilities. Here's a summary of what it can do.

Creation modes

vary has 5 creation modes at the moment:

Parent: The most common way to approach theming is using a body/parent class.
Insert (Body + HTML class): If you need to apply the body class on a selector that contains an HTML class.
Modifier (BEM): When differently styled modules need to be present on the same page, the most common approach is to create a modifier.
Append: Appends an .is-entity class to the selector.
Custom: A vary playground. You can create any kind of construction.

Check out the demos page to see the creation modes in action.

Flexibility

It's nice that vary goes through every entity for you, but on some cases you may want something different for specific entities only or to exclude some from the list. Maybe you even have multiple maps to loop through.

Well, vary has your back. On the current version of vary you have support for:

Targeted entities: Using the $for parameter you can make vary go through some of the entities from them map, not all of them.
Excluded entities: The reversed version of the targeted ones. Using the $not parameter, you can exclude entities so vary doesn't loop through them.
Multiple maps: By default, vary will loop through the entities in $vary-map. But if you have multiple maps of the same kind, you can set any map using the $loop parameter and vary will loop through it instead of the default one.

It also allows you to have a centralised set of variables that can be accessed using the vary-get function. Check out the docs to know more about the functions and mixins included.

How to get it

vary is licensed under the MIT license and totally available on GitHub and it is currently mantained by me, Jaime Caballero.

To get a copy you can get the latest version from GitHub or use Bower:

bower install sass-vary --save

Once you get it, import it into your project and put these into your variables file.

$vary-libsass: true;

$vary-map: (
  user: (
    'color-primary': blue,
    'border': '1px solid #ff0'
  ),
  admin: (
    'color-primary': pink,
    'border': '10px solid black'
  )
);

Set up your $vary-map with the entities and colours relative to your project and you are ready to go!