Scoped Styles in the Visual Builder

The UltraCart StoreFronts Visual Builder allows you to apply custom CSS styles that are scoped directly to the selected element and its child elements. This guide explains how to use scoped styles effectively, including special keywords, theme variables, and an understanding of element structure.

Quick Reference: Special Keywords and Theme Variables

You can use the following special keywords and a function to apply specific styling rules:

Keyword / Function	Description	Example Usage

Keyword / Function	Description	Example Usage
`parent`	Adds a direct child combinator (`>`) after the automatically generated prefix, targeting direct children of the element.	`parent p { color: blue; }`(Targets `<p>` elements that are direct children)
`ancestor`	Applies the automatically generated prefix before the selector you provide. This allows you to style the selected element based on it being an ancestor of another element within your CSS. For example, ancestor .other-class will apply styles to the selected element if it is an ancestor of .other-class.	`ancestor .some-child-class { background-color: blue; }` (Applies background-color: blue to the selected element if it is an ancestor of .some-child-class.)
`self`	Applies the automatically generated prefix directly to the selector without extra spacing, allowing you to target the element itself with pseudo-classes or more specific rules.	`self:hover { opacity: 0.8; }` (Changes opacity when the element is hovered)
`themecolor("Theme Color Name")`	A function that allows you to access colors defined in your StoreFronts Theme settings. Replace `"Theme Color Name"` with the exact name of your theme color (e.g., `"Theme Color 05"`).	`color: themecolor("Theme Color 05")` `border-bottom: 1px solid themecolor("Primary Accent");`

How Scoped Styles Work

When you add custom styles in the Scoped Style Tag editor within the Visual Builder, these styles are applied with a unique prefix that targets the currently selected element. This ensures that your custom CSS only affects the intended element and its descendants, preventing unintended style conflicts across your StoreFront.

The editor preserves comments (e.g., /* This is a comment */), whitespace, and formatting, allowing you to organize your CSS clearly.

Handling Pseudo-classes

Pseudo-classes (e.g., :hover, ::before, :active, :focus) and pseudo-elements are fully supported and will be correctly appended to the automatically generated prefix for the selected element.

Example:

/* Apply a hover effect to the selected element itself */
self:hover {
  background-color: #f0f0f0;
}

/* Add content before a direct child paragraph */
parent p::before {
  content: "Read: ";
  font-weight: bold;
}

Understanding Element Structure

When applying styles, it's crucial to understand the underlying HTML structure of UltraCart StoreFront elements. Styles are applied to the outermost container of the selected element. However, many elements contain an inner content wrapper (e.g., .widget-panel-content or .widget-flex-content) where child elements reside.

For instance, consider these common element structures:

Panel Element Structure:

<div id="panel-615588" data-widget-type="panel" class="widget widget-panel ">
   <div class="widget-panel-content">
     <!-- child elements and content... -->
   </div>
</div>

Flex Element Structure:

<div id="flex-615588" data-widget-type="flex" class="widget widget-flex ">
   <div class="widget-flex-content">
     <!-- child elements and content... -->
   </div>
</div>

If you need to apply styles that affect the layout or appearance of the contents within a panel or flex element (such as display: flex or grid properties), you should target this inner content container.

Example:

To make the direct children of a panel element arrange themselves as a flex container, you would target its widget-panel-content div:

/* Apply flex styles to the content area of the selected panel */
parent .widget-panel-content {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

Inspecting Element Structure

To view the precise HTML structure of an element without any additional editor classes or structure applied by the Visual Builder, we recommend opening your StoreFront page in an incognito window of your browser and using your browser's developer tools to "Inspect" the element. This will show you the clean, live DOM structure.

Custom Classes

UltraCart allows you to add custom CSS classes to most elements. These classes provide a flexible way to apply reusable styles across multiple elements or to target specific elements with custom CSS rules defined outside of the scoped styles editor.

Adding Custom Classes

The input field for custom classes is located in the element settings within the CSS area, under the Display Options section.

You can enter multiple custom classes by separating them with spaces, for example: class_one class_two class_three.

How Custom Classes are Applied

When you add custom classes, they are applied directly to the main container div of the element, alongside its default UltraCart classes.

Example:

If you add my-custom-class and another-style to a panel element, the HTML would look like this:

<div id="panel-615588" data-widget-type="panel" class="widget widget-panel my-custom-class another-style">
   <div class="widget-panel-content">
     <!-- child elements and content... -->
   </div>
</div>

Targeting Custom Classes

You can target these custom classes using the following methods:

Inline CSS Editor (Scoped Styles): Use the self keyword with your custom class.
Override CSS: Found in the StoreFronts Backend UI.
File Manager: Via stylesheets uploaded to your StoreFront.
Any external stylesheet that is called into your StoreFronts page.

Example targeting your custom class in the Inline CSS Editor (Scoped Styles):

self.my-custom-class {
  background-color: #fff;
}