Include CSS

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.

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.

/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, to include <theme_dir>/web/css/custom.css:

<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/custom.css"  src_type="url" rel="stylesheet" type="text/css"  />
    </head>
</page>

The following illustrates how stylesheets are included in the default Blank theme:

[/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>

To include an external CSS file, add <css src="URL to External Source" src_type="url" rel="stylesheet" type="text/css" />.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <css src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css"  src_type="url" rel="stylesheet" type="text/css"  />
    </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.

Jan 29th, 2020

Edit this page on GitHub

Give us feedback