Using CSS Handles for store customization

Introduction

CSS Handles is a HTML elements identifier. Therefore, it can be used to customize any of your store components by simply using CSS classes through the store theme's code.

At the end of the day, CSS Handles are nothing more than your store's layout building assistants. Follow the step-by-step below and find out how to use them in a fast and simple way!

Step by step

1. While you are viewing your workspace on your browser, add ?__inspect at the end of the URL of the page, and press enter. For example, https://yourworkspace--youraccount.myvtex.com?__inspect. Note that it must be a development workspace, rather than a production one, and it must be under the domain myvtex.com.

2. Hover on the element you want to customize. It should display its available CSS handles in a box (the large names beginning with .), along with their respective CSS file names, and other information.

3. Open the Store Theme code using the code editor of your preference. Then, create a file inside the css folder named after the text displayed below the desired handle. Following the example above, we would have vtex.menu.css.

4. In the new file, use one of the CSS handles listed and customize its properties. For example:

.menuItem {  
    background: rgba(0, 0, 0, 0.2);
    margin: 5px;
    border-radius: 5px;
}

Once you app is linked and the changes duly saved, the new customization should immediately be reflected onto your workspace.

As we've seen, CSS Handles are used to overwrite a store's default style and thus independently customize a type of block from the rest of the theme. Note that the change above was applied to all menu-item blocks.

To independently customize a single menu-item block, you should use the blockClass prop.

blockClass is a property whose value you may define freely. When passed onto a block, it serves as its single identifier for customization.

Using the blockClass property

1. In the json file where your block is declared, add the prop blockClass to the element you want to customize, with any name as a value.

For example:

"menu-item#your-item": {
  "props": {
    ...,
    "blockClass": "header"
  },
  ...
}

After saving and updating your workspace, when you inspect the element it should display an additional CSS handle along with its default one, like this:

After that, you can use the class .menuItem--header to target specifically the elements that have this blockClass.

Best practices

In order to standardize CSS customization and avoid any potential breakdown in layout, we recommend store customization to be performed exclusively using CSS Handles.

However, it's common to come across store scenarios whose customization uses CSS Selectors. As the name implies, they are used to select elements for CSS customization according to the page HTML hierarchy.

This customization practice by HTML hierarchy was mostly deprecated. It means that only the CSS Selectors listed below will continue to be allowed for your store customization:

• Class selectors (e.g. .foo)
• Pseudo-selectors :hover, :visited, :active, :disabled, :focus, :local, :empty, and :target
• :not()
• :first-child and :last-child
• :nth-child(even), :nth-child(odd), and :nth-child(2n) (or any other step like 4n, 5n, etc)
• All pseudo-elements, such as ::before, ::after and ::placeholder
• Space combinator (e.g. .foo .bar)
• [data-...]
• :global(vtex-{AppName}-{AppVersion}-{ComponentName}) for selection of elements that come from different apps

Any CSS Selectors not on this list, such as :nth-child(2), foo > bar and [alt="bar"], it's not accepted by Toolbelt during the linking of the store's theme with its local files.