Stylus BEM Sugar

Collection of Stylus mixins that help write code in BEM notation.

• Installation
• Javascript API
• Usage
  • Examples
    • Block
    • Element
    • Modifier
    • Nesting
    • Group
• Using with Gulp
• Contributions

Installation

$ npm install stylus-bem-sugar

Javascript API

var stylusBemSugar = require('stylus-bem-sugar'),
    stylus = require('stylus');

function compileStylus(str) {
	return stylus(str)
           .use(stylusBemSugar());
}

Options:

You can customize produced selectors by passing options object to module call with appropriate values:

var options = {
  elementPrefix: '__',
  modifierPrefix: '--',
  modifierDelimiter: '_'
}

stylusBemSugar(options);

Usage

To use mixins import them in your stylus file:

@import 'bem-sugar'

Examples

Block

+b('header')
  color: blue

Compiles to:

.header {
  color: #00f;
}

Element

+b('header')
  color: blue
  +e('logo')
    float: left

Compiles to:

.header {
  color: #00f;
}
.header__logo {
  float: left;
}

Modifier

+b('header')
  color: blue
  +m('theme', 'seagreen') // accepte optional mod value arg
    background-color: green

  +e('logo')
    float: left
    +m('absolute')
      position: absolute;

Compiles to:

.header {
  color: #00f;
}
.header--theme_seagreen {
  background-color: #008000;
}
.header__logo {
  float: left;
}
.header__logo--absolute {
  position: absolute;
}

Nesting

Elements can nest in mods:

+b('header')
  +m('theme', 'seagreen')
    +e('foo')
      color: #333

Compiles to:

.header--theme_seagreen .header__foo {
  color: #333;
}

Elements can nest in elements:

  +e('nav')
    +e('nav-item')
      font-size: 1.5em

Compiles to:

.header__nav .header__nav-item {
  font-size: 1.5em;
}

Depth is not limited

+b('header')
  +m('level1')
    +e('level2')
      +e('level3')
        +m('level4')
          +e('level5')
            // ...
            color: #000

Compiles to:

.header--level1 .header__level2 .header__level3--level4 .header__level5 {
  color: #000;
}

Group

In some cases you can group your selectors by using special group mixin:

+b('header')
  // Note:
  // 1. mixins should be called without `+` prefix
  // 2. style rules should be placed on the
  //    same indentation level
  +group()
    e('foo')
    e('baz')
    e('bar')
    e('egg')
    color: #333
    line-height: 1.2

  // Mods also can be grouped
  +group()
    m('mod1')
    m('mod2')
    color: #747474
    font-size: 12px

Compiles to:

.header__foo,
.header__baz,
.header__bar,
.header__egg {
  color: #333;
  line-height: 1.2;
}
.header--mod1,
.header--mod2 {
  color: #747474;
  font-size: 12px;
}

Using with Gulp

// ...
var stylus = require('gulp-stylus');
var stylusBemSugar = require('stylus-bem-sugar');

var options = {
  stylus: {
    use: stylusBemSugar()
  }
}

galp.task('compile:stylus', function() {
  return gulp.src('src/main.styl')
    .pipe(stylus(options.stylus))
    .pipe(gulp.dest('public/css/'))
});
// ...

Contributions

Please, if you find a bug, write an issue or make a pull request.