A site for Joomla! documentation

Joomla Developer Manual

Manual Index

SCSS and Sass

Most of the Joomla 4.x default stylesheets are written using SCSS and then compiled to generate the CSS files.

Where can you find the .scss stylesheets and compiler?

The core .scss files are in different directories. Specifically, these are these filesː

  • templates/cassiopeia/scss/template.scss
  • administrator/templates/atum/scss/bootstrap.scss
  • administrator/templates/atum/scss/font-awesome.scss
  • administrator/templates/atum/scss/template.scss
  • administrator/templates/atum/scss/template-rtl.scss
  • media/plg_installer_webinstaller/scss/client.scss

The CSS generation script, SCSS compiler, and other similar build tools are located in the build/ directory of the Joomlaǃ source located on GitHub. Refer to Git for Coders for more information on using GitHub. The build directory is only available from the Joomlaǃ source, it is not included in an official Joomlaǃ release.

Prerequisites

Compiling your own SCSS files with Joomlaǃ core requires your local machine to have Node.js installed in it. To install Node.js, please go to the Node.js official web site, download the respective setup for your operating system and install it by following the installation wizard. NPM (Node Package Manager) is used to manage and setup the JavaScript testing environment.

Install dependencies (packages)

Open a command line and navigate to the root directory of Joomla 4.x.

Execute command npm install

    $ npm install
    ...
    added 1354 packages in 193.687s
    $

This will install all the dependencies to the /node_modules directory. If a /node_modules folder does not exist, a folder will be automatically created by npm. It is OK, if you see some warnings, but you should not see an error message.

How to re-generate the CSS style sheets

To re-generate all the CSS files from a Joomlaǃ core distribution, you will need to execute the generation scripts as a CLI application.

All Joomlaǃ core scss files

You can compile all Joomlaǃ core css files with the command npm run build:css. For exampleː

    $ npm run build:css
    Prefixing for:  last 1 version
    Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning.
    template.css was updated.
    Prefixing for:  last 1 version
    template-rtl.css was updated.
    Prefixing for:  last 1 version
    font-awesome.css was updated.
    Prefixing for:  last 1 version
    client.css was updated.
    Prefixing for:  last 1 version
    bootstrap.css was updated.
    Prefixing for:  last 1 version
    template.css was updated.
    $

All files in one directory

You can compile all files in one directory with the command node build --compile-css path-to-directory. For exampleː node build --compile-css templates/cassiopeia/scss.

    $ node build --compile-css templates/cassiopeia/scss
    Prefixing for:  last 1 version
    Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning.
    template.css was updated.

One special file

You can compile one file with the command node build --compile-css pathtofile. For exampleː node build --compile-css templates/cassiopeia/scss/template.scss.

    $ node build --compile-css templates/cassiopeia/scss/template.scss
    Prefixing for:  last 1 version
    Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning.
    template.css was updated.

Noteː

  • The file extension .scss must be lowercase.
  • The css file must be created.

Compiling your own SCSS files for your template

To compile scss files for your own template, you will need to take a copy of the JOOMLA4/build/build-modules-js/compilecescss.js script and adjust it to suit your environment.

Alternatively you can use a SCSS Compiler plugin which compiles your .scss files automatically on page reload. In the Joomlaǃ Extension Directory JED you will find a plugin for this purposeː Joomlaǃ Extension Directory

More alternatives and tools you can find on http://sass-lang.com/install

The SCSS compiler used for the Joomlaǃ 4.x core is node-sass. In the Joomlaǃ core you can find it in the directory JOOMLA4/node_modules/node-sass.

Difference CSS, SCSS and Sass

SCSS or Sass simplifies CSS notation and defines variables. This ensures a clearer presentation, less code and a simpler revision through the use of variables.

CSS

With CSS we write code like below in full lengthː

        #header {
          margin: 0;
          border: 1px solid blue;
        }
        #header p {
          font-size: 14px;
          color: blue;
        }
        #header a {
          text-decoration: none;
        }

Sass

Sass is a CSS preprocessor with syntax improvements. Style sheets in the extended syntax are processed by the preprocessor and converted into regular CSS style sheets.

There are two syntaxes available for Sassː SCSS and Sass.

SCSS

SCSS is used in Joomlaǃ core. SCSS is an extension of the syntax of CSS.

        $color:    blue;
        #header {
          margin: 0;
          border: 1px solid $color;
          p {
            color: $colorRed;
            font: {
              size: 14px;
            }
          }
          a {
            text-decoration: none;
          }
        }

Sass

The older Sass syntax provides a more concise way of writing CSS.

        $color:    blue
        #header
          margin: 0
          border: 1px solid $color
          p
            color: $colorRed
            font:
              size: 14px
          a
            text-decoration: none

You can find more information in the Sass Documentation.

From existing CSS to SCSS / import CSS files

You may want to add your existing CSS files and classes to your SCSS powered Cassiopeia template or start with what you have. All CSS declarations are compatible with SCSS so you can just rename your .css files to .scss and you can compile and use them. You can then step by step make use of the features SCSS has to offer:

  • Language extensions such as variables, nesting, and mixins
  • Many useful functions for manipulating colors and other values
  • Advanced features like control directives for libraries
  • Well-formatted, customizable output

See https://sass-lang.com/

Notice: If you want to customize Cassiopeia template it is a good idea to copy the template and customize it afterwards - so that Joomla! updates do not overwrite your customizations.

Import your .css as .scss files

Now lets assume you want to include your custom files and get them parsed by SCSS compiler - you do NOT need to rewrite your .css to SCSS because plain .css works as well. The only thing you have to do is

  • to rename your .css files to .scss and
  • prefix it with an _ and
  • add an @import statement into above mentioned main templates/cassiopeia/scss/template.scss

I assume you put your custom mystyles.css file renamed to _mystyles.scss into the /templates/cassiopeia/scss folder. Now you open /templates/cassiopeia/scss/template.scss and at the bottom of the file your _mystyles.scss file so that it overrides existing declarations:

    // Bootstrap functions
    @import "../../../media/vendor/bootstrap/scss/functions";


    // Variables
    @import "variables";

    // Flying Focus
    @import "../../../media/vendor/flying-focus-a11y/scss/flying-focus";

    // Bootstrap
    @import "../../../media/vendor/bootstrap/scss/variables";
    @import "../../../media/vendor/bootstrap/scss/bootstrap";

    // FontAwesome
    @import "../../../media/vendor/font-awesome/scss/font-awesome";

    // B/C for Icomoon
    @import "../../../media/system/scss/icomoon";

    // Alert
    @import "../../../media/system/scss/jalert";

    // Blocks
    @import "blocks/global"; // Leave this first
    @import "blocks/alerts";
    @import "blocks/banner";
    @import "blocks/demo-styling";
    @import "blocks/footer";
    @import "blocks/form";
    @import "blocks/frontend-edit";
    @import "blocks/header";
    @import "blocks/icons";
    @import "blocks/iframe";
    @import "blocks/layout";
    @import "blocks/modals";
    @import "blocks/modifiers";
    @import "blocks/utilities";
    @import "blocks/css-grid"; // Last to allow fallback

    // Vendor overrides
    @import "vendor/awesomplete";
    @import "vendor/bootstrap/buttons";
    @import "vendor/bootstrap/card";
    @import "vendor/bootstrap/custom-forms";
    @import "vendor/bootstrap/collapse";
    @import "vendor/bootstrap/dropdown";
    @import "vendor/bootstrap/lists";
    @import "vendor/bootstrap/modal";
    @import "vendor/bootstrap/nav";
    @import "vendor/bootstrap/pagination";
    @import "vendor/bootstrap/table";
    @import "vendor/chosen";
    @import "vendor/dragula";
    @import "vendor/minicolors";
    @import "vendor/tinymce";

    @import "mystyles";

If you now compile your main template.scss file you end up with one main template.css optimized and minified. You also reduced your http requests and the site should load faster.