BEM CSS class naming

Contract

Enforces the block__element--modifier class-naming grammar on every CSS class you name for a UI component. Apply whenever the task is to name the classes for a component and its parts and states; not to write the CSS declarations themselves and not to choose visual values.

Rules

A component's class names are built from three kinds of name, joined by fixed delimiters:

1. Block — the standalone component, named on its own: card, modal, nav. Words within

a single name are joined by a single hyphen: site-header, product-card.

1. Element — a part that belongs to a block, joined to the block name with a double

underscore __: card__title, modal__close, nav__item. Never a single hyphen (card-title), never camelCase (cardTitle), never a descendant selector (.card .title).

1. Modifier — a variant or state flag on a block or element, joined with a double hyphen

--: card--featured, nav__item--active, button--disabled.

1. No element of an element. Elements are always exactly one level under the block. A part

nested visually inside another part is still block__thing, never block__part__thing: write card__title, not card__header__title.

1. A modifier never stands alone. It is applied alongside the base class, not instead of

it: class="button button--primary", never class="button--primary" by itself. The modifier only adjusts; the base carries the shared styles.

1. Case + separators. All name parts are lowercase. The three separators are distinct and

fixed: single hyphen - inside a multi-word name, double underscore __ before an element, double hyphen -- before a modifier.

Worked examples

The base's ad-hoc default is on the left; the conforming BEM names on the right.

A search form with a field, a submit control, and a disabled state:

BEFORE  .searchForm   .searchForm .input   .submitBtn   .disabled

AFTER   .search-form
        .search-form__field
        .search-form__submit
        .search-form--disabled

A media object (image beside body text) with a reversed variant:

BEFORE  .media   .media-img   .mediaBody   .media.reverse

AFTER   .media
        .media__image
        .media__body
        .media--reversed

An element that carries its own state — the modifier attaches to the element, used with it:

BEFORE  <li class="active">   /* bare state class */

AFTER   <li class="breadcrumb__crumb breadcrumb__crumb--current">

Edge cases & exceptions

• Deeply nested markup → the class is still block__element. A label inside a field inside

a form is search-form__label, not search-form__field__label. Flatten to one level.

• A part that is really its own component → promote it to a new block. A reusable button

inside a card is button (its own block), not card__button, when it is used elsewhere too.

• Multiple modifiers → list each as its own class alongside the base:

class="button button--large button--primary".

• Boolean state vs value → a plain flag is --active/--disabled; a value uses a

key-value form --size-large / --theme-dark (still the double-hyphen delimiter).

Do / Don't

• Do join an element to its block with __. Don't use a single hyphen (card-title),

camelCase (cardTitle), or a descendant selector.

• Do join a modifier with --. Don't use a single hyphen or a bare state class like .active.
• Do keep elements one level under the block. Don't chain block__a__b.
• Do apply a modifier alongside the base class. Don't replace the base with the modifier alone.
• Do lowercase every part. Don't PascalCase or camelCase block/element names.

Common mistakes

• Ad-hoc names the base reaches for: .cardTitle, .card-title, .card .title, .active.
• Single underscore/hyphen where a double belongs (card_title, card-title for an element;

button-primary for a modifier).

• Chaining elements: menu__list__item instead of menu__item.
• A lone modifier class in the markup with no base class.
• Mixing camelCase into a name part.

Quick checklist

• Each part class is block, block__element, or block[__element]--modifier.
• Element delimiter is __; modifier delimiter is --; both are doubled.
• No element is chained under another element.
• Every modifier appears alongside its base class, never alone.
• All name parts are lowercase, words joined by single hyphens.