bem-join
v2.0.2
Published
A function used to construct BEM class names.
Downloads
986
Readme
bem-join
A single, configurable function used to construct BEM class names.
- No dependencies.
- Super tiny footprint @ under 500 bytes (min + gzip).
- Works great with or without React.
- Generated TypeScript definitions packaged with each build/release.
Installation
$ npm install bem-join
Usage
The bemJoin
function can be used to construct BEM class names. In most cases, you can just import this module and use it directly in each component. To illustrate this, let's create a simple Section
component:
// /src/components/Section.jsx
import { bemJoin } from 'bem-join';
const b = bemJoin('section');
The above example uses the default options of __
for the element separator and --
for the modifiers. If you need to customize the element and modifier separators, see the Custom Separators section below.
The new b
function from above can be called in two different ways:
b( [blockModifiers] )
Constructs the BEM block class names (e.g., foo foo--mod1 foo--mod2
).
See the BEMModifiers
section below for the modifiers interface.
b( elementName [, elementModifiers] )
Constructs the BEM element class names (e.g., foo__bar foo__bar--mod1 foo__bar--mod2)
).
See the BEMModifiers
section below for the modifiers interface.
Let's see it in action!
export const Section = ({ children, heading, isDark, isExpanded }) => (
<section className={b({ dark: isDark })}>
<h1 className={b('heading')}>{heading}</h1>
<div className={b('body', { expanded: isExpanded })}>{children}</div>
</section>
);
If isDark
and isExpanded
props were both truthy, the result would be the
following HTML:
<section class="section section--dark">
<h1 class="section__heading">
Heading
</h1>
<div class="section__body section__body--expanded">
children
</div>
</section>
Of course, if isDark
and isExpanded
were falsey, no --dark
or --expanded
modifiers would be constructed for them.
For ultimate reuse, you might consider allowing all of your components to accept an optional blockName
prop that changes the default block name. To do this, you just need to move your first bem-join
call inside of your render function. Here's an example of what that would look like:
export const Foo = ({ blockName, children }) => {
const b = bemJoin(blockName || 'foo');
return <div className={b()}>{children}</div>;
};
BEMModifiers
Interface
All modifiers must be provided as a Record
object with Boolean
or undefined
values:
export type BEMModifiers = Record<string, boolean | undefined>;
Custom Separators
If your application requires custom element and modifier separators, you can easily do so by creating your own module that calls this one with configuration options as the first argument. Export the result of that and you can reuse it throughout your application. Here's an example:
// ./src/helpers/bem-join.js
import { bemJoin as _bemJoin } from 'bem-join';
export const bemJoin = _bemJoin({
elementSeparator: '__', // <-- default
modifierSeparator: '--', // <-- default
});
The exported function is now ready to be used in your application. Here's an example import for a component:
import { bemJoin } from '../helpers/bem-join';
From here, everything is the same as previously stated in the Usage section.
Testing
Run the following command:
$ npm test
.