Important

You are browsing upcoming documentation for version 5.1 of OroCommerce, OroCRM, and OroPlatform, scheduled for release in March 2023. Read version 5.0 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Stylesheets (SCSS)

CSS Architecture

Front UI in core Oro applications is based on the Oro UI library, which, in its turn, is based on the adjusted Bootstrap v.4 toolkit.

Note

Refer to the Oro Frontend Stylebook article for detailed description of the Oro UI library.

Oro applications use the SCSS extension and a preprocessor to define CSS.

OroCommerce project is composed of bundles. Each bundle has its own set of CSS related to a particular bundle. Additionally, OroCommerce project has two themes which are default, and custom.

SCSS files as other template assets (images as javascripts) and layout update files are grouped into themes. Out-of-the-box, the OroCommerce application comes with two themes, default, and custom.

  1. default - a fully developed theme and recommended for customizations. It has basic @mixins, @functions, variables, color palette, typography, settings and dependencies.
  2. custom - a modified default theme

CSS Files Structure

Assets for each theme are located in a particular theme folder, e.g., BundleName/Resources/public/{theme_name}/scss/.

Core styles are located in UIBundle: UIBundle/Resources/public/default/scss/.

CSS structure has three folders, components, settings, and variables:

  1. components - a folder for bundle components;
  2. settings - a folder for @mixins, @functions, and settings for a particular theme;
  3. variables - a folder for all configuration variables for a particular bundle.

Each bundle has its own styles.scss that collects all variables, settings, and components styles.

To enable css for a particular theme, add the styles.scss file name to the assets.yml file in the appropriate bundle, e.g., BundleName/Resources/views/layouts/{theme_name}/config/assets.yml.

An example of the three folders structure (e.g., the BundleName/Resources/views/layouts/{theme_name}/scss/ folder):

components/
    page-container.scss
    page-content.scss
    page-footer.scss
    page-header.scss
    page-title.scss
settings/
    global-settings.scss
variables/
    page-container-config.scss
    page-content-config.scss
    page-footer-config.scss
    page-header-config.scss
    page-title-config.scss
styles.scss
BundleName/Resources/views/layouts/{theme_name}/scss/styles.scss
@import 'components/page-container';
@import 'components/page-header';
@import 'components/page-content';
@import 'components/page-footer';
@import 'components/page-title';
BundleName/Resources/views/layouts/{theme_name}/config/assets.yml
css:
    inputs:
        - 'bundles/orofrontend/default/scss/settings/global-settings.scss'
        - 'bundles/orofrontend/default/scss/variables/base-config.scss'
        - 'bundles/orofrontend/default/scss/variables/page-container-config.scss'
        - 'bundles/orofrontend/default/scss/variables/page-header-config.scss'
        - 'bundles/orofrontend/default/scss/variables/page-content-config.scss'
        - 'bundles/orofrontend/default/scss/variables/page-footer-config.scss'
        - 'bundles/orofrontend/default/scss/variables/page-title-config.scss'
        # You can import Sass modules from node_modules.
        # Just prepend them with a ~ to tell Webpack that this is not a relative import.
        # See: https://webpack.js.org/loaders/sass-loader/#resolving-import-at-rules
        - '~prismjs/themes/prism-coy.css'
    auto_rtl_inputs:
        # List of file masks for inputs that has to be processed with RTL plugin
        - 'bundles/oro*/**'
    output: 'css/styles.css'

Compiler collects all styles in one file for the theme. All files should be sorted by priority. There are files with a settings folder at the top followed by variables and all styles.scss at the end.

Example:

application/commerce/public/build/{theme_name}/css/styles.css.scss
@import "../bundles/orofrontend/default/scss/settings/global-settings.scss";
@import "../bundles/orofrontend/default/scss/variables/base-config.scss";
@import "../bundles/orofrontend/default/css/variables/page-container-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-header-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-content-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-footer-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-title-config.scss";
@import "../bundles/orocms/default/scss/styles.scss";
@import "~prismjs/themes/prism-coy.css";

This structure enables us to change styles for components on a bundle level, on a component level and for a particular theme. The main idea of this approach is not to override styles in a child theme from the parent one. We just change settings and add additional CSS(SASS).

Define Custom Primary Settings and Variables

To customize primary settings and variables (such as colors, fonts, etc.), create the Resources/views/layouts/{theme_name}/config/assets.yml file in your theme and write the following config in it:

Resources/views/layouts/{theme_name}/config/assets.yml
css:
    inputs:
        - 'bundles/{your_bundle}/{theme_name}/scss/settings/primary-settings.scss'
        - 'bundles/{your_bundle}/{theme_name}/scss/variables/primary-variables.scss'

Create files settings/primary-settings.scss and variables/primary-variables.scss accordingly with the desired variables definition. They will pop up within the import list of the build’s entry point file:

application/commerce/public/build/{theme_name}/css/styles.css.scss
@import "../bundles/{your_bundle}/{theme_name}/scss/settings/primary-settings.scss";
@import "../bundles/orofrontend/default/scss/settings/global-settings.scss";
@import "../bundles/{your_bundle}/{theme_name}/scss/variables/primary-variables.scss";
@import "../bundles/orofrontend/default/scss/variables/base-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-container-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-header-config.scss";
@import "../bundles/orofrontend/default/css/variables/page-content-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-footer-config.scss";
@import "../bundles/orofrontend/default/scss/variables/page-title-config.scss";
@import "../bundles/orocustomer/default/scss/styles.scss";
@import "~prismjs/themes/prism-coy.css";

Override and Disable SCSS Files

To remove or override scss/css, create the Resources/views/layouts/{theme_name}/config/assets.yml file in your theme and write the following config in it:

Resources/views/layouts/{theme_name}/config/assets.yml
css:
    inputs:
        - 'bundles/oroform/default/scss/styles.scss': ~ // file will be removed from build process
        - 'bundles/oroform/default/scss/styles.scss': 'bundles/oroform/{theme_name}/scss/styles.scss' // file will be overridden

Theme Extending

In order to inherit one theme from another, define the parent theme in the theme.yml file.

For example, if you need to inherit the custom theme from default, perform the following:

/theme.yml
parent: default

It enables you to inherit all styles from the parent theme and have access to all mixins, variables, etc. from the parent one.

Here is an example of using the custom theme. The aim is to change the global settings and the appearance of form elements. For this, we create theme folders and several scss files in the corresponding bundles (FrontEndBundle, FormBundle).

CustomThemeBundle/Resources/public/FrontendBundle/scss/
settings/
    global-settings.scss
variables/
    page-main-config.scss
CustomThemeBundle/Resources/views/layouts/custom/config/assets.yml
    inputs:
        - 'bundles/orocustomtheme/FrontendBundle/scss/settings/main/global-settings.scss'

        - 'bundles/orocustomtheme/FrontendBundle/scss/variables/page-main-config.scss'
    output: 'css/styles.css'
FormBundle/Resources/public/default/scss/
components/
    header.scss
settings/main/
    global-settings.scss
variables/
    breadcrumbs-config.scss
styles.scss

Update and add new variables for this component

breadcrumbs-config.scss
$breadcrumbs-offset: 12px 0; // update the variable's value with custom theme

Add missing styles for this component

header.scss
@include breakpoint('tablet') {
    .page-header {
        .middlebar {
            &__right {
                display: block;
            }
        }
    }
}
styles.scss
    @import './components/header';

In the main file of the custom theme, we have:

application/commerce/public/build/default/styles.css.scss
@import "../bundles/oroui/default/scss/settings/global-settings";

// Update global setting for main styles
@import "../bundles/orocustomtheme/FrontendBundle/scss/settings/main/global-settings";

*// Update setting from global components*
@import "../bundles/orofrontend/default/scss/variables/page-main-config"
@import "../bundles/orocustomtheme/FrontendBundle/scss/variables/page-main-config"

*// Update styles for page-main component*
@import "../bundles/orofrontend/default/scss/styles";
@import "../bundles/orocustomtheme/FrontendBundle/scss/styles";

Themes Settings and Useful Recommendation

  1. Main styles for the default theme: package/platform/src/Oro/Bundle/UIBundle/Resources/public/default/scss/
    • mixins: package/platform/src/Oro/Bundle/UIBundle/Resources/public/default/scss/settings/mixins/
    • variables: package/customer-portal/src/Oro/Bundle/FrontendBundle/Resources/public/default/scss/variables/
    • typography: package/platform/src/Oro/Bundle/UIBundle/Resources/public/default/scss/settings/partials/_typography.scss
    • color pallet: package/platform/src/Oro/Bundle/UIBundle/Resources/public/default/scss/settings/_colors.scss
  2. Form styles for default theme: package/platform/src/Oro/Bundle/FormBundle/Resources/public/default/scss

Related Topics

The best practices of the frontend development in Oro applications are provided in the Oro Frontend Development Guidelines.

We recommend to use them as examples for your custom code.