Simple ways to customize a theme's styles

What’s in this topic

Let’s say you created a new theme inheriting from Magento Blank or Luma, and chose the Less compilation mode. What’s next? Where to add the style changes? This topic gives quick answers.

Simplest way to extend parent styles

To extend the parent theme’s styles in your theme:

In your theme directory, create a web/css/source sub-directory.

Create a _extend.less file there. The path to it looks like following:

 <theme_dir>/
 │  ├── web/
 │  │   ├── css/
 │  │   │   ├── source/
 │  │   │      ├──_extend.less
 ...

Add your Less code in this file.

Extending a theme using _extend.less is the simplest option when you are happy with everything the parent theme has, but want to add more styles.

The rules and variables declared in _extend.less always have precedence over ones declared in _theme.less.

Simplest way to override parent styles

To override parent styles (that is, override default Magento UI library variables):

In your theme directory, create a web/css/source sub-directory.
Create a _theme.less file here. The path to it then looks like following:
```
<theme_dir>/
│  ├── web/
│  │   ├── css/
│  │   │   ├── source/
│  │   │      ├──_theme.less
...
```
It is important to remember that your _theme.less overrides the parent _theme.less.
Copy all variables you need from the parent _theme.less, including those which will not be changed. For example if your theme inherits from Blank, the _theme.less you should copy from is located at <Magento_Blank_theme_dir>/web/css/source/_theme.less.
Make the necessary changes.

The drawback of this approach is that you need to monitor and manually update your files whenever the parent’s _theme.less is updated.

Adding structured changes

To make your changes easier to read and support, structure them by adding a separate overriding or extending .less files for each Magento UI library component you change. Let’s use the button component implemented in _button.less as an illustration.

Extend component’s styles

In your theme directory, create a web/css/source sub-directory.

Add _buttons_extend.less and _extend.less here. The path to the files looks like following:

<theme_dir>
│  ├── web/
│  │   ├── css/
│  │   │   ├── source/
│  │   │      ├──_buttons_extend.less
│  │   │      ├──_extend.less
...

In _buttons_extend.less add your styles for the button component.
In _extend.less register the _buttons_extend.less by adding the following code: @import '_buttons_extend.less';

Override component’s styles

To override the parent theme’s styles for buttons in your theme:

In your theme directory, create a web/css/source sub-directory.

Create a _buttons.less file here. The path to it looks like following:

<theme_dir>/
│  ├── web/
│  │   ├── css/
│  │   │   ├── source/
│  │   │      ├──_buttons.less
...

This file overrides the _buttons.less of the parent theme.

Add your styles for the button component. If the file is left blank, then no styles are applied for the component.

Extend module styles

To extend a Module’s styles in your theme:

In your theme directory, create a Module_Name/web/css/source directory.

Create an _extend.less file in the theme directory. For example:

<theme_dir>/
├── <module_dir>/
│   ├── web/
│   │   ├── css/
│   │   │   ├── source/
            ├──_extend.less
...

Add additional styles in the _extend.less file.

For example, to extend the Magento_Review module’s style, the directory path should be <your_theme_dir>/Magento_Review/web/css/source/_extend.less.

Override module styles

To override module styles in your theme:

In your theme directory, create a Module_Name/web/css/source directory.

Create a _module.less file in the theme directory. For example:

<theme_dir>/
├── <module_dir>/
│   ├── web/
│   │   ├── css/
│   │   │   ├── source/
            ├──_module.less
...

This file overrides the _module.less file of the specific module.

Add your styles in the _module.less file.

For example, to override the Magento_Review module’s style, the directory path should be <your_theme_dir>/Magento_Review/web/css/source/_module.less.