Close [x]

Include CSS

Edit this page on GitHub

What's in this topic

In the Magento application, CSS files are included in layout files.

Technically there is an option to include them in template files, but we strongly recommend avoiding this.

The CSS class names can be assigned in both templates and layouts.

This topic describes how stylesheets are located by default in the Magento application file system, and the recommended way to include CSS files in layouts.

How Magento stylesheet files are organized

Conventionally, CSS and LESS files are stored only in themes. Module directories do not contain any default styles.

In a theme directory, stylesheets are stored in the following locations:

Directory, relative to <theme_dir> Description
/<Namespace>_<Module>/web/css Module-specific styles
/web/css Contains the following:
  • print.less: used to generate styles for the printed version of store pages.
  • _styles.less - a composite file, which includes all LESS files used in the theme. The underscore sign ("_") in a file name conventionally means that a file is not used independently, but is included in other files.
  • styles-m.less: used to generate mobile-specific styles, includes _styles.less
  • styles-l.less: used to generate desktop-specific styles, includes _styles.less.
  • /source: this subdirectory contains LESS configuration files that invoke mixins from the Magento UI library
  • /source/_theme.less: overrides the default Magento UI library variables values.

Include CSS

In the Magento application, the recommended way to include stylesheets is to specify them in layout files.

Usually, the stylesheets you include should be available for all store pages. To achieve this, include your CSS in default_head_blocks.xml of the Magento_Theme module, which defines the default <head> page section for all Magento pages. The recommended way to do this is adding an extending default_head_blocks.xml in your theme, and including the required stylesheets in this file.

Your custom default_head_blocks.xml should be located as follows: <theme_dir>/Magento_Theme/layout/default_head_blocks.xml.

To include a CSS file, add the <css src="<path>/<file>" media="print|<option>"/> block in <head> section in a layout file. <path> is specified relative to the theme web directory (<theme_dir>/web) For example, the following illustrates how stylesheets are included in the default Blank theme:

<Magento_Blank_theme_dir>/Magento_Theme/layout/default_head_blocks.xml

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <css src="css/styles-m.css" />
        <css src="css/styles-l.css" media="screen and (min-width: 768px)"/>
        <css src="css/print.css" media="print" />
    </head>
</page>

If the system does not find the included CSS files, it searches for the same file names with a .less extension. This is part of the built-in preprocessing mechanism. You can find more information about it in the CSS Preprocessing topic.