qbem

A quick BEM helper! More BEM. Less Typing.

/*
 *         ._.
 *         | | +-+ QUICK-BEM +-+
 *     __._| |_.   .__.   ._. ._.
 *  . / _. | ._ \./ _  \. / _V_ \.   * Block
 *   | (_| | |_) |  __./.| ||_|| |   * Element
 *  . \__, |_.__/.\___|. |_|   |_|.  * Modifier
 * ------| |------------------------
 *      .|_|. More BEM. Less Typing.
 */

Install

Using yarn

yarn add qbem

Using npm

npm install qbem

Usage

Quick Guide

/* import or require */
import { QBem } from 'qbem';

/* or */
require { QBem } from 'qbem';

/* create an instance of QBem with your block name */
/*        doesn't matter what you name it          */
/*          I like 'qb' b/c it's short             */

const qb = new QBem('form');


/* need your block style? Do this: */
qb.block(); // returns: 'form'

/* need modifiers for your block? Do this: */
qb.block(['active']); // returns: 'form form--active'

/* want to make those modifiers conditional? Do this: */
qb.block([
  {
   ['active']: someTrueCondition,
   ['inactive']: someFalsyCondition, // modifiers with falsy conditions won't be added
  }
]); // returns: 'form form-active'

/* need an element? Do this: */
qb.element('input'); // returns: 'form__input'

/* need modifiers for your element? Do this: */
qb.element('input', ['active']); // returns: 'form__input form__input--active'

/* want to make those modifiers conditional? Do this: */
qb.element(
  'input',
  [
    {
      ['active']: someTrueCondition,
      ['inactive']: someFalsyCondition, // modifiers with falsy conditions won't be added
    }
  ]
); // returns: 'form__input form__input--active`

Use anywhere you template HTML

const qb = new QBem('form');

const template = `
<form class="${qb.block(['theme-xmas', 'simple'])}">
  <input class="${qb.element('input')}" type="text" />
  <input
  class="${qb.element('submit', ['disabled'])}"
  type="submit" />
</form>
`;

Results in:

<form class="form form--theme-xmas form--simple">
  <input class="form__input" type="text" />
  <input
  class="form__submit form__submit--disabled"
  type="submit" />
</form>

Use with React

// ToggleBtn.tsx
// ...
const qb = new QBem('toggle-btn');

const ToggleBtn: FC = (props) => {
  const { text, isActive } = props;

  return (
    <div className={qb.block()}>
      <span className={qb.element('text')}>
        {text}
      </span>
      <button
        className={qb.element(
          'button',
          [{
            enabled: isActive,
            disabled: !isActive,
          }]
        )} />
    </div>
  );
}

Creating a new instance of QBem

/* import */
import { QBem } from 'qbem';

/* create an instance per block */
const qb = new QBem('block-name');

Block

qb.block(); // block-name

Add modifiers to a block using a string array

qb.block(['active']); // block-name block-name--active
qb.block(['active', 'dark-mode']); // block-name block-name--active block-name--dark-mode

Use conditional modifiers (conditional object keys added as BEM modifier when values are true)

qb.block([
  {
    active: true,
    ['dark-mode']: true,
    disabled: false, // falsy values not added
  },
]); // block-name block-name--active block-name--dark-mode

Use mixed modifiers

qb.block([
  'active',
  'dark-mode',
  {
    disabled: false, // falsy values not added
  },
]); // block-name block-name--active block-name--dark-mode

Element

Block name is automatically added to elements

qb.element('element'); // block-name__element

Add modifiers to elements using a string array

qb.element('element', ['active']);
// block-name__element block-name__element--active

qb.element('element', ['active', 'dark-mode']);
// block-name__element block-name__element--active block-name__element--dark-mode

API

Constructor

QBem(blockName: string) -- Creates a new QBem object using the supplied blockName.

The blockName will be used as the "block" portion of BEM strings created with the instance.

Methods

blockWithModifier(modifier: string)

Manual method for creating a BEM style class string for a BEM block with a BEM modifier using the BEM block name associated with this instance of QBem.

elementWithModifier(element: string, modifider: string)

Manual method for creating a BEM style class string for a BEM element with a BEM modifier using the BEM block name associated with this instance of QBem.

block(modifiers: (string | QBemConditionalModifier)[] | undefined = [])

Method for creating a BEM style class string. Uses the BEM block name associated with this instance of QBem.

element(element: string, modifiers: (string | QBemConditionalModifier)[] | undefined = [])

Method for creating a BEM style class string. Uses the BEM block name associated with this instance of QBem and the supplied BEM element name.