Extending Parent Styles in Custom Theme using Less

Extending Parent Styles in Custom Theme using Less

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

  1. Create a _extend.less file there. The path to it looks like following:
    │ ├── web/
    │ │ ├── css/
    │ │ │ ├── source/
    │ │ │ ├──_extend.less
  2. 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.

Overriding Parent Styles in Custom Theme using Less

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

  1. In your theme directory, create a web/css/source sub-directory.
  2. Create a _theme.less file here. The path to it then looks like following:
    │ ├── web/
    │ │ ├── css/
    │ │ │ ├── source/
    │ │ │ ├──_theme.less
  3. It is important to remember that your _theme.less override the parent _theme.less.
  4. 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
  5. Make the necessary changes.
  6. It might be possible that the parent theme doesn’t have _theme.less file. It’s just for a reference. If there is a file with name _module.less in <Magento_Blank_theme_dir>/Magento_Theme/web/css/source then you need to copy the same file in your theme at similar location  <theme_dir>/Magento_Theme/web/css/source and then make required changes into this file

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

Note: To see the changes that you had made in the less file, you need to perform setup:upgrade and setup:static-content:deploy.

Less Compilation with Grunt


Make sure that you set your Magento application to the developer or default mode.

Installing and configuring Grunt

Magento has built-in Grunt tasks configured, but there are still several prerequisite steps you need to take to be able to use it:

  1. Install node.js to any location on your machine. Refer: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions
  2. Install Grunt CLI tool globally. To do this, run the following command in a command prompt:
    npm install -g grunt-cli
  3. Now Rename the following files:
    Gruntfile.js.sample to Gruntfile.js
    package.json.sample to package.json
  4. Install (or refresh) the node.js project dependency, including Grunt, for your Magento instance. To do this, run the following commands in a command prompt:
    cd <your_Magento_root_directory>
    npm install
    npm update
  5. Add your theme to Grunt configuration. To do this, in the dev/tools/grunt/configs/themes.js file, add your theme to module.exports like following:
    module.exports = {
     <theme>: {
     area: 'frontend',
     name: '<Vendor>/<theme>',
     locale: '<language>', 
     files: [
     '<path_to_file1>', //path to root source file
     dsl: 'less'

    Where the following notation is used:

    <theme>: your theme code, conventionally should correspond to the theme directory name.

    <language>: specified in the ‘code_subtag’ format, for example en_US. Only one locale can be specified here. To debug the theme with another locale, create one more theme declaration, having specified another value for language

    <path_to_file>: path to the root source file, relative to the app/design/frontend/<Vendor>/<theme/>web directory. You need to specify all root source files of the theme. If your theme inherits from a certain theme, and does not contain its own root source files, specify the root source files of the parent theme.

  6. (Optional) If you want to use Grunt for “watching” changes automatically, without reloading pages in a browser each time, install the LiveReload extension in your browser.
Grunt Commands
Command Usage
grunt clean:<theme>

For example:

grunt clean:blank

It removes the theme related static files in the pub/static and var directories.
grunt exec:<theme> It republishes symlinks to the source files to the pub/static/frontend/<Vendor>/<theme>/<locale> directory.
grunt less:<theme> Compiles .css files using the symlinks published in the pub/static/frontend/<Vendor>/<theme>/<locale> directory
grunt watch Tracks the changes in the source files, recompiles .css files, and reloads the page in the browser pages (you need to have LiveReload installed for you browser)

Basically, you need to use grunt less:<theme> which would compile less.