BEM Components Library

bem-components is an open-source library that provides a set of ready-made visual components (blocks) for creating web interfaces.

The library provides design themes. This version introduces the islands theme, which implements the new Yandex design. Features include supporting multiple themes at once, and creating new themes.

Contents

• Levels
• Blocks
• Supported browsers
• Technologies
• Tools
• Usage
• Development
• Maintainers
• Workflow

Additional information

• Changelog
• Migration to future versions

Levels

• common.blocks — support of any devices and browsers.
• desktop.blocks — support of desktop browsers.
• touch.blocks — implementation of specific features for touch platforms.
• touch-phone.blocks — implementation of specific features for smartphones.
• touch-pad.blocks — implementation of specific features for tablets.
• design/<common|desktop|touch|touch-phone|touch-pad>.blocks — implementation of various designs (themes).

Blocks

• attach
• button
• checkbox
• checkbox-group
• control
• control-group
• dropdown
• icon
• image
• input
• link
• menu
• menu-item
• modal
• popup
• progressbar
• radio
• radio-group
• select
• spin
• textarea
• z-index-group

Supported browsers

• Desktop

  • Firefox (the last two stable versions)
  • Chrome (the last two stable versions)
  • Safari (the last two stable versions)
  • Yandex (the last two stable versions)

• Touch

  • Android 5+
  • iOS 12+

Technologies

• ES modules
• i-bem.js
• BEMHTML
• DEPS
• PostCSS

Tools

Build

• Vite — build tool and dev server
• PostCSS — CSS processing (via Vite)
• Autoprefixer — vendor prefixes

Code analysis

• ESLint 10 — JavaScript linting

Testing

• Playwright — browser regression testing

Usage

Installation

npm install bem-components

Requirements: Node.js >= 20

Peer dependencies:

• bem-core ^5.0.0
• jquery ^4.0.0

Building from source

git clone https://github.com/bem/bem-components.git
cd bem-components
npm install
npm run build

The build produces output for three platforms in the dist/ directory:

• dist/desktop/
• dist/touch-pad/
• dist/touch-phone/

Library concepts

The block and its states

The library consists of blocks, which you can see represented visually in the bem-components showcase. Blocks have states that determine the behavioral model. A block’s state is expressed through modifiers and specialized fields. Changing a modifier creates an event that can be used for working with the block.

There is no need to create a special BEM event if you can work with the modifier change event. Depending on what is used for changing a component’s state (a modifier or a field), different events are used:

• To respond to changing the "state" of value fields, the change event is used.
• To respond to setting or removing a modifier, various modifier change events are used.

Controls in bem-components

The controls in bem-components can be used as the basis for creating other library components. Such controls don't have models as in HTML, and they can be used for tasks that don't require the semantics of a specific HTML model.

As an example, think of the "behavioral model" for the HTMLInputElement, which is a higher-level interface designed specifically for editing data. What is different about bem-components blocks is that they can be used as the basis of a block in another library that will solve the same problem. But along with that, they can serve other purposes in the interface that don't require HTML input semantics.

Implementation details

focused modifier

Controls in bem-components have two types of focus, which are set using the modifiers focused and focused-hard. The type of focus determines the appearance of the control.

The modifier is chosen automatically based on how the focus is set:

• focused — Set for a mouse click on the control.
• focused-hard — Set when the control is selected using the keyboard or through JavaScript. It highlights the component more obviously when it gets the focus. For example, in the Islands theme, most of the controls get an extra border when focused-hard is set.

Development

• Working copy
• How to contribute
• Testing

Working copy

Get sources:

git clone git://github.com/bem/bem-components.git
cd bem-components

Install dependencies:

npm install

Build all platforms:

npm run build

Start the development server:

npm run dev

Code analysis:

npm run lint

Testing

Browser regression tests

Playwright is used for browser testing.

npm run test:browser        # run tests headless
npm run test:browser:ui     # run tests with Playwright UI

Run all checks

npm test                    # runs lint + test:browser

Tests are run automatically on GitHub Actions for each pull request.

Maintainers

• veged
• dfilatov
• tadatuta

Workflow

Current tasks are tracked via GitHub Issues.

License

Code and documentation © 2012 YANDEX LLC. Code released under the Mozilla Public License 2.0.