React with BEM

react-with-bem implements the BEM methodology for React.

Installation

Use your favourite manager to install the package:

yarn add react-with-bem

npm install react-with-bem --save

Usage

import React from "react";
import { BEM } from "react-with-bem";

// import styles as module
// https://github.com/css-modules/css-modules
import styles from "./App.module.scss";

// use BEM annotations whenever applicable
export function App() {
    return (
        // activate BEM and inject styles
        <BEM styles={styles}>
            {
                // set BEM block by using $block
                // output: <main class="app">
            }
            <main $block="app">
                {
                    // set a BEM element by using $element
                    // output: <div class="app__container">
                }
                <div $element="container">
                    {
                        // set BEM modifier by using $modifier (multiple modifiers are possible)
                        // output:
                        //     <div class="app__container__hello> when emphasized === false
                        //     <div class="app__container__hello app__container__hello--emphasized"> when emphasized === true
                    }
                    <div
                        $element="hello"
                        $modifier={{
                            emphasized: true,
                        }}
                    >
                        Hello World!
                    </div>
                </div>
            </main>
        </BEM>
    );
}

.app {
    background-color: red;
    color: white;

    &__container {
        max-width: fit-content;
        margin: 0 auto;

        &__hello {
            font-size: 2rem;

            &--emphasized {
                font-weight: bold;
            }
        }
    }
}

Please note:

• The use of CSS modules is optional. If you do not want to use CSS modules, leave out the styles parameter of the <BEM> component.
• If you set the class name map via the styles parameter of the <BEM> component, it will be used to map the vanilla BEM class names to the CSS module class names generated by your compiler framework.
• Good to know: BEM class names will be filtered out if they are missing in the provided class name map. It can happen if the Saas compiler filters out empty CSS classes. It is not a problem, but it might confuse you if you inspect the generated class names in the DOM inspector.

ESLint

Please add the following rule to your ESLint configuration to suppress errors related to the $block, $element, and $modifier attributes.

{
    "rules": {
        "react/no-unknown-property": [
            2,
            { "ignore": ["$block", "$element", "$modifier"] }
        ]
    }
}

Example

You can find a complete example here.

Reference

<BEM> component

The <BEM> activated the BEM processing for its children tree. It accepts one optional property.

• styles?: Record<string, string>: Use this optional property to provide the imported CSS module class name map. If provided, it will be used to map the vanilla BEM class names to the CSS module class names generated by your compiler framework.

BEM properties

The library activates the following optional BEM properties available on all components. The BEM properties will be removed and translated to the className?: string property. So you should apply the BEM properties only to components that provide the className property.

• $block?: string: Name of the BEM block. Using this property will reset the calculated BEM path.
• $element?: string | string[]: Name of the BEM element or nested BEM elements. The name or names will be appended to the calculated BEM path.
  • Note: You can also use leading dots to navigate upwards of the element hierarchy. A single dot has no effect, whereas each additional dot removes the last element from the calculated BEM path.
• $modifier?: string | string[] | Record<string, boolean>: Name or names of the BEM modifier to be applied. If the map annotation is used, only the ones who evaluate to true will be applied.