BEM naming conventions

We structure our CSS using the BEM pattern.

Our naming convention for blocks, elements and modifiers has evolved over the years. This card shows our current style and various alternative styles that you might encounter in older projects.

The difference between the various styles are mostly a matter of taste and optics. I do recommend to not mix styles and be consistent within a given project.

Current convention

Our current BEM naming convention looks like this:

Copy<div class="user-info -pro">
  <img class="user-info--avatar" ...>
  <div class="user-info--name">...</div>
</div>

Note how the modifier just starts with a dash (-pro). It is not prefixed with the block name. The modifier's block is always unambiguous due to the other class on the same DOM node.

This style was adopted from Nico Hagenburger Show archive.org snapshot .

Older conventions

Modifier prepositions

We used prefix modifiers with a preposition or helping verb, e.g. is-pro or has-child:

Copy<div class="user-info is-pro">
  ...
</div>

We now just use -pro and -child.

Underscores

We used to separate words with underscores:

Copy<div class="user_info is_pro">
  <img class="user_info__avatar" ...>
  <div class="user_info__name">...</div>
</div>

We now use dashes (-), which feels more CSS-y.

What other teams do

There are a lot of different BEM naming conventions out there.

A common convention separates elements with double underscores (__) and modifiers with double dashes (--):

Copy<div class="user-info user-info--pro">
  <img class="user-info__avatar" ...>
  <div class="user-info__name">...</div>
</div>

Because of its popularity you might encounter this in an external codebase.