Magento UI library

What's in this topic

The Magento UI library is a flexible LESS-based frontend library designed to assist Magento theme developers. It employs a set of mixins for base elements to ease frontend theme development and customization.

This topic describes how the library is organized, and how to use it.

Components provided by the UI library

The Magento UI library provides the ability to customize and reuse the following user interface elements and properties:

• actions-toolbar
• breadcrumbs
• buttons
• drop-downs
• forms
• icons
• layout
• loaders
• messages
• pagination
• popups
• ratings
• sections
• tabs and accordions
• tables
• tooltips
• typography
• list of theme variables

The following illustration shows a storefront product page containing some of the preceding elements:

Mixin location

You can find the Magento UI library under lib/web/css. Library source .less files are stored under the source directory, each file contains mixins for configuring a certain element, and in most cases the element coincides with the file name:

lib/web
    ├── css/
    │    ├── docs/ (Library documentation)
    │    ├── source/
    │    │    ├── lib/ (Library source files)
    |    |    |    ├── variables/ (Predefined variables for each mixin)
    │    │    │    ├── _actions-toolbar.less
    │    │    │    ├── _breadcrumbs.less
    │    │    │    ├── _buttons.less
    │    │    │    ├── _dropdowns.less
    │    │    │    ├── _forms.less
    |    |    |    ├── _grids.less
    │    │    │    ├── _icons.less
    │    │    │    ├── _layout.less
    │    │    │    ├── _lib.less
    │    │    │    ├── _loaders.less
    │    │    │    ├── _messages.less
    │    │    │    ├── _navigation.less
    │    │    │    ├── _pages.less
    │    │    │    ├── _popups.less
    │    │    │    ├── _rating.less
    │    │    │    ├── _resets.less
    │    │    │    ├── _responsive.less
    │    │    │    ├── _sections.less
    │    │    │    ├── _tables.less
    │    │    │    ├── _tooltips.less
    │    │    │    ├── _typography.less
    │    │    │    ├── _utilities.less
    │    │    │    └── _variables.less
    │    │    └── _extend.less
    │    │    └── _theme.less
    │    │    └── _variables.less
    │    └── styles.less
    ├── fonts/
    │    └── Blank-Theme-Icons/ (Library custom icons font)
    ├── images/
    │    └── blank-theme-icons.png (Library icons sprite)
    └── jquery/ (Library javascript files)

Predefined variables

If your theme inherits from any Magento out-of-the-box theme, for example Blank, you can easily customize any element of a store page without changing any CSS code or templates. Customization can be performed by simply changing in your theme the values of the predefined variables used in the UI library or parent theme mixins.

The complete list of these variables and their default values are stored in lib/web/css/source/lib/variables. This directory contains a set of files, corresponding to the set of UI library elements, and each of the files lists element-specific variables. For example, lib/web/css/source/lib/variables/_breadcrumbs.less contains variables used in the breadcrumbs() mixin.

To change the default library variables values, specify the new values for the required variables in the <theme_dir>/web/css/source/_theme.less file.

The following figure shows the product page shown earlier in this topic, after a custom theme was applied. The theme customized Blank by redefining variables only.

Your custom variables

When naming custom variables, please follow the Magento naming convention for the LESS variables.

Using mixins

You can use a mixin with default variables values, or you can redefine them when calling a mixin. The following paragraphs describe both ways to call a mixin.

To use a mixin with default values, call the mixin without specifying any parameters. For example:

.breadcrumbs {
    .breadcrumbs();
}

To call a mixin with parameter values different from default, set these values when calling the mixin, like in the following example:

.example-button {
    .button(
        @_button-padding: @button-padding,
        @_button-color: #fff,
        @_button-color-hover: #ccc
    );
}

Variables starting with @_ are private mixin variables used only in this mixin. Variables starting with @ (without the underscore) are global, and are listed in lib/web/css/source/lib/variables/.

UI library documentation

You can find detailed information about the Magento UI library in the documentation provided together with the code:

• lib/web/css/docs/source/README.md: describes the Magento UI library structure, naming conventions, and code style.
• lib/web/css/docs: contains a set of .html files with detailed information about the library mixins. Each file is named after the mixin it describes, and contains detailed mixin description and navigation controls to access documentation for other mixins. The documentation is available in a convenient HTML view in the following location in your Magento installation: pub/static/frontend/Magento/blank/en_US/css/docs/index.html