BEM Cheatsheet

gistfile1.md

BEM Cheatsheet

Checklist:

• Blocks are descriptive and independent of other class names.
• Elements are semantically tied to a block.
• Neither elements nor modifiers are “nested.”
• In the CSS, block and element classes are defined independently.
• Modifiers are only used for variation/flag purposes.
• In the HTML, modifiers are only used alongside the original classes that they modify.

BLOCK

Blocks are indepenent components that can be reused

There is no precedence or hierarchy.

Holistic entities without DOM representation (such as controllers or views) can be blocks as well.

Naming

Block name may consist of Latin letters, digits, and dashes.

HTML

Any DOM node can be a block if it accepts a class name.

<div class="nav-bar">...</div>

CSS for blocks

• Use class name selector only
• No tag names (e.g., div, span, p) or id's
• No dependency on other blocks/elements on a page

.nav-bar {
    color: $dk-orange;
}

ELEMENT

Elements are parts of a block that are only used within their parent block.

Any element is semantically tied to its block.

Do not "nest" elements.

HTML

Any DOM node within a block can be an element. Within a given block, all elements are semantically equal.

Naming

Element name may consist of Latin letters, digits, and dashes.

CSS class is formed as block name + two undercores + element name: .nav-bar__item

<!-- Bad--no nesting of elements -->
<div class="nav-bar">
  ...
  <span class="nav-bar__admin__item"></span>
</div>

<!-- Good -->
<div class="nav-bar">
  ...
  <span class="nav-bar__item"></span>
</div>

CSS for elements

• Use class name selector only
• No tag name or id's
• No dependency on other blocks/elements on a page

  /* BAD */   .nav-bar .nav-bar__item { border: solid 1px #000 }
  /* BAD */   div.nav-bar__item { border: solid 1px #000 }
  
  /* GOOD  */ .nav-bar__item { border: solid 1px #000 }

MODIFIER

Modifiers are variations in style of blocks or elements.

Use them to change appearance or behavior.

Do not use modifiers when an element would be more appropriate.

Do not "nest" modifiers.

HTML

Modifier is an extra class name which you add to a block/element DOM node.

Naming

Modifiers (both keys and values) may consist of Latin letters, digits, and dashes.

Modifier can be a boolean flag or a key/value pair. Naming conventions:

• Boolean modifiers:
  Original block/element name + double dash + mod name
  .nav-bar--hidden or .nav-bar__item--hidden
• Key/value modifiers:
  Original block/element name + double dash + mod key name + single underscore + mod value
  .byline--staff_contributor or .byline__name--staff_columnist

Add modifier classes only to blocks/elements they modify, and keep the original class:

  <!-- Good --> <div class="byline byline-community">...</div>
  <!-- Good --> <div class="byline byline--staff byline--emeritus">...</div>
  
  <!-- Bad - Missing original class -->  <div class="byline--community">...</div>
  <!-- Bad - Element makes more sense here -->  <div class="byline byline--title">...</div>
  <!-- Bad - No nesting modifiers -->  <div class="byline byline--staff--emeritus">...</div>

CSS for modifiers

Use modifier class name as selector:

.nav-bar--hidden {
    display: none;
}

To alter elements based on a block-level modifier:

.byline--community .byline__title {
    color: $community-blue;
}

Element modifier:

.byline__title--community {
    color: $community-blue;
}

This file's a decent example, IMO: https://github.com/dailykos/dailykos/blob/release/app/assets/stylesheets/ui/subscriptions/new.scss

  <!-- Good --> <div class="byline byline-community">...</div>

  <!-- Good --> <div class="byline byline--community">...</div>

?