Skip to content

Theming API V2

Apptus eSales Lifestyle is designed and themed out of the box in a way that follows many best practices in e-commerce. However, one design theme will not fit all sites. The Theming API v2 allow for easy customisation of several design elements used by the eSales Lifestyle components.

Overview

All theming customisations are provided via CSS custom properties and CSS shadow parts.

Theming of texts can be made on a broader level by setting the overall typography properties, affecting multiple components at once. This is recommended to be used primarily when altering the general typography, as it automatically provides consistency across the components.

Various other types of theming can be made by directly styling either the web components or their exposed parts and properties. This can also be used for very targeted typography styling when needed.

All custom properties are set on the :root. Only properties that differ from their default values should be specified.

:root {
  --ae-font-family: Roboto, Arial, sans-serif;
}

::part(breadcrumbs) {
  color: black;
  font-size: 14px;
  text-decoration: underline
}

::part(badge sale) {
  font-size: 12px;
  color: white;
  width: 22px;
  height: 22px;
  background: red;
  border-radius: 50%;
}

Legacy browser support

If support for legacy Edge (v18 or lower) is required, use html instead of :root inside media queries. Legacy Edge does not properly recognize the :root selector inside media queries, and will ignore these rules.

@media (max-width: 580px) {
  html { /* Note: html instead of :root */
    --ae-font-family: Roboto, Arial, sans-serif;
  }
}

Applying theming

By default, a stylesheet handling the look-and-feel for mobile usage is automatically applied for all web components. Custom theming can be built from scratch, but it is recommended that it is based off the default stylesheet as not to forget handling responsiveness for all parts.

Another recommendation is to provide all eSales component styling as a separate stylesheet, as this is beneficial from a performance perspective. Provided stylesheets should follow the requirements in the Shadow part shim section to enable the provided theming for older browsers.

The following step-by-step guide ensures that all best practices are followed:

  1. Download the default stylesheet, available at https://cdn.esales.apptus.com/integration/v1/esales-lifestyle-responsive.css
  2. Modify the stylesheet for the desired look-and-feel, following the specification in this section.
  3. Host the CSS-file on your domain.
  4. Make the CSS-file available to all pages on your site via:
    <link class="esales-lifestyle-stylesheet" rel="stylesheet" href="[filename].css">
    Note that the class esales-lifestyle-stylesheet is required.
  5. Add disableResponsiveStyleSheet: true as a property to the script initialisation.
  6. Success!

Typography

Typography properties will affect several components which is suitable for general, consistent text styling. If a specific component or part needs specific typography, styling can be adjusted through specific parts and properties.

All typography theming properties have a default value. Only properties that differ from their default values should be specified.

General

Custom property Type Default value Description
--ae-font-family string inherit The font family of the text in eSales components.

Affected parts and components

All parts and components, where not explicitly overridden by another value.

Headline

Custom property Type Default value Description
--ae-headline-color string rgba(00,00,00, 0.87) The colour of the headline.
--ae-headline-font-size string 29px The font size of the headline in pixels.
--ae-headline-font-weight string 600 The font weight of the headline.
--ae-headline-letter-spacing string 0.25px The letter-spacing setting of the headline.

Affected parts and components

Title

Custom property Type Default value Description
--ae-title-color string rgba(00,00,00, 0.87) The colour of the title.
--ae-title-font-size string 19px The font size if the title in pixels.
--ae-title-font-weight string 800 The font weight of the title.
--ae-title-letter-spacing string 0.25px The letter-spacing setting of the title.

Affected parts and components

Label

Custom property Type Default value Description
--ae-label-color string rgba(00,00,00, 0.87) The colour of the label.
--ae-label-font-size string 13px The font size of the label in pixels.
--ae-label-font-weight string 700 The font weight of the label.
--ae-label-letter-spacing string 0.4px The letter-spacing setting of the label.

Affected parts and components

Body

Custom property Type Default value Description
--ae-body-color string rgba(00,00,00, 0.87) The colour of the body text.
--ae-body-font-size string 13px The font size of the body text in pixels.
--ae-body-font-weight string 400 The font weight of the body text.
--ae-body-letter-spacing string 0.4px The letter-spacing setting of the body text.
--ae-body-sale-color string #DF4538 The colour of the body sale text.

Affected parts and components

Body-2

Custom property Type Default value Description
--ae-body2-color string rgba(00,00,00, 0.87) The colour of the body-2 text.
--ae-body2-font-size string 11px The font size of the body-2 text in pixels.
--ae-body2-font-weight string 400 The font weight of the body-2 text.
--ae-body2-letter-spacing string 0.4px The letter-spacing setting of the body-2 text.

Affected parts and components

Product title

Custom property Type Default value Description
--ae-product-title-color string rgba(00, 00, 00, 0.87) The colour of the product title.
--ae-product-title-font-family string inherit The font family of the product title.
--ae-product-title-font-style string none The font style of the product title.
--ae-product-title-font-size string 13px The font size of the product title in pixels.
--ae-product-title-font-weight string 400 The font weight of the product title.
--ae-product-title-letter-spacing string 0.4px The letter-spacing setting of the product title.
--ae-product-title-text-transform string none The text-transform setting of the product title.

Affected parts and components

Product subtitle

Custom property Type Default value Description
--ae-product-subtitle-color string rgba(00, 00, 00, 0.87) The colour of the product subtitle.
--ae-product-subtitle-font-family string inherit The font family of the product subtitle.
--ae-product-subtitle-font-style string none The font style of the product subtitle.
--ae-product-subtitle-font-size string 11px The font size of the product subtitle in pixels.
--ae-product-subtitle-font-weight string 400 The font weight of the product subtitle.
--ae-product-subtitle-letter-spacing string 0.4px The letter-spacing setting of the product subtitle.
--ae-product-subtitle-text-transform string none The text-transform setting of the product subtitle.

Affected parts and components

Parts and properties

All custom properties and exposed parts are grouped by the area or components that they affect. All custom properties are set on the root.

A part is a CSS pseudo-element that represents any element within a CSS shadow tree that has a matching part-attribute. Parts are styled in the same way as any regular HTML element, and can be used together with media queries other selectors as well as several pseudo-states. Parts natively support pseudo-states that considers the state of the part itself without dependencies to other elements, including:

:after
:before
:focus
:active
:hover

Some parts also have a set of additional states that are supported. State part support is found in the specification next to each part.

/* Basic part styling */
::part(facet-item) {
  background-color: teal;
}

/* Pseudo-state part support */
::part(facet-item):hover {
  background-color: pink;
}

/* State part support */
::part(facet-item open) {
  background-color: green;
}

/* Media query support */
@media (max-width: 1000px) {
  ::part(facet-item) {
     background-color: blue;
  }
}

/* Scoped part styling */
.spaced::part(facet-item) {
  margin: 12px;
}

For more information about CSS ::part(), see Mozilla Developer Network.

General

Custom property Type Default value Description
--ae-mobile-width string 576px The breakpoint where components will switch from desktop to mobile layout.
Part State part support Description
breadcrumbs N/A Breadcrumb list element.
breadcrumb Inactive Breadcrumb list item element.
breadcrumb-separator N/A Breadcrumb separator element.

Buttons

Part State part support Description
button N/A Button usually containing an icon used for clearing facets etc.
button-primary N/A Primary button used in facets and search assistant etc.
button-quick-buy N/A Quick-buy button used in product cards.

Badges

Part State part support Description
badge sale, discount, new, theme_1, theme_2, theme_3 Base badge. Rules applied to this part will apply to all badges.
badge-primary sale, discount, new, theme_1, theme_2, theme_3 Badge displayed in the image area of a product card.
badge-secondary sale, discount, new, theme_1, theme_2, theme_3 Badge displayed in the description area of a product card.

Category title

Part State part support Description
category-title N/A Displays the current active category on a navigation page.

Facets

Custom property Type Default value Description
--ae-facets-per-row string auto How many facets should be visible in one row. Can be set with either a number or with auto, which will make the facets size according to its content instead of how many should be visible per row.
--ae-facets-justify-content string left Uses same values as justify-content. Is used to position facets horizontally.
--ae-facet-wrapper-height string 325px Sets the height of the drop-down box containing the facet-values.
--ae-facet-wrapper-max-height string 325px Sets the max height of the drop-down box containing the facet-values.
--ae-facet-color-mode string grid The layout of facet values. Can be either list or grid.
--ae-facet-size-mode string grid The layout of facet values. Can be either list or grid.

Facet item

Part State part support Description
facet-item open, active Facet item which opens the dropdown on click.
facet-item-count N/A Count shown in the facet item to display how many values are selected.
facet-item-dropdown N/A A dropdown container containing facet values.
facet-item-dropdown-search-field N/A A search field shown in the top of the dropdown container.

Facet (select)

Part State part support Description
facet-select-list-item selected Facet value list items.
facet-select-list-item-value N/A Text content of list item.
facet-select-list-item-count N/A Count shown on facet value list items.
facet-select-list-item-icon selected Icon displaying if a facet value is selected or not.

Facet (colour)

Part State part support Description
facet-color-item N/A Facet colour item.
facet-color-item-title N/A Text content of colour item.
facet-color-item-swatch N/A Facet colour item swatch.

Facet (range)

Part State part support Description
facet-range-handle N/A Drag-able handle for a numeric facet range.
facet-range-track inactive The track connecting the two handles.

Facet (size)

Part State part support Description
facet-size-list N/A Facet size list-item.
facet-size-list-item selected Facet size list.
facet-size-title N/A Text content of list items.

Facet chips

Part State part support Description
facet-chip N/A Item displaying currently selected facet-values.
facet-chip-clear N/A A button which clears all currently selected values.
facet-chip-clear-wrapper N/A Wraps the clear button to make it possible to add spacing and border between the chip and the button.

Favourites

Enable before use

The parts must be enabled with --ae-product-card-favorites-enabled before use. For more information, see Product card.

Part State part support Description
favorite-button N/A Button element.
favorite-button-icon N/A Icon element within the button element.
Custom property Type Default value Description
--ae-show-navigation-count boolean false Decides if count should be displayed in navigation nodes.
Part State part support Description
navigation-tree-list N/A Navigation tree list element.
navigation-tree-list-item selected, disabled Navigation tree list item element.
navigation-tree-subtitle N/A Navigation tree item subtitle element.
navigation-tree-icon N/A Navigation tree item icon element.

Product list

Part State part support Description
product-list-load-more N/A Load more button used in the bottom of a product list.
product-list-load-more-wrapper N/A Wrapper containing load more button used in the bottom of a product list.

Product card

Custom property Type Default value Description
--ae-product-cards-per-row number 3 How many product cards should be visible in one row.
--ae-product-card-vertical-spacing number 24 The amount of vertical space in pixels between product cards in a search result. The value must be numeric only.
--ae-product-card-horizontal-spacing number 24 The amount of horizontal space in pixels between product cards in a search result. The value must be numeric only.
--ae-product-image-height-ratio number 1.2 Image ratio of product card.
--ae-product-card-info-align string center Aligns the info within the product card, i.e. left or center.
--ae-product-card-title-rows number 1 The number of rows used for the product card title. Can be either 1 or 2.
--ae-product-card-thumbnail-hint-size string 10px The width and height of the thumbnail hints within the product card info.
--ae-product-card-thumbnail-hint-margin string 9px 3px 0 The margin of the thumbnail hints within the product card info.
--ae-rating-icon-color string #333 The colour of the filled rating icons. All valid CSS colours and methods can be used.
--ae-rating-position string image Can be either image or bottom.
--ae-product-quick-buy-position string none The placement of the Quick buy button within the product card. Can be either top, bottom, or none. Use none to not display the button.
--ae-product-card-favorites-enabled boolean false Can be either true or false. Toggles a favourite icon inside the product card.
Part State part support Description
product-card-thumbnails N/A List of thumbnails of variants displayed when hovering a product card.
product-card-thumbnail-item N/A Item displaying a variant.
product-card-thumbnail-hints N/A Thumbnail hints shown when the product card is not hovered.
product-card-sizes N/A A list of available sizes of a product.
product-card-size-item N/A Item displaying a size value.
product-card-rating N/A Displays the rating of a product.
product-card-product-title multiple-rows The title of the product displayed in the product card.
product-card-product-brand N/A The brand of the product displayed in the product card.
product-card-product-price N/A The price of the product displayed in the product card.

Preamble text

Part State part support Description
preamble-text N/A Wrapper element of preamble text.
preamble-button N/A A button which appears to enable expanding the preamble text if the text is too long.
preamble-text-content N/A Text content of the preamble text.

Ratings

Enable before use

The part must be enabled with ratings:true set inside the esales.init function before use. For more information, see Script Initialisation.

Part State part support Description
ratings active Rating item.

Recommendations

Part State part support Description
recommendations N/A Product listing of recommendations.

Search assistant

Custom property Type Default value Description
--ae-search-assistant-box-shadow string 0 0 3px rgba(0, 0, 0, 0.5) The box-shadow of the input field and suggestions pop-up.
--ae-search-assistant-border-color string rgb(235, 235, 235) The border colour of the search assistant.
--ae-search-assistant-height string 43px The height of the input field.
--ae-search-assistant-font-size string 15px The font size of the input field.
--ae-search-assistant-border-radius string 0 The border radius of the input field.
--ae-search-assistant-clear-icon-size string 22px The font size of the clear-icon in the input field.
--ae-search-assistant-mobile-button-size string 24px The font size of the mobile search-icon.
--ae-search-assistant-product-card-title-rows string 1 The number of rows used for the product card title. Can be either 1 or 2.

Product suggestions

Part State part support Description
product-suggestion-title N/A The title of a product displayed in a product suggestion.
product-suggestion-brand N/A The brand of a product displayed in a product suggestion.
product-suggestion-price N/A The price of a product displayed in a product suggestion.

Search result

Part State part support Description
search-result-filter-actions N/A A wrapper containing a filter and a category button.
search-result-filter-button N/A A button opening a filter modal.
search-result-category-button N/A A button opening a category modal.
search-result-category-header N/A The header of the category modal.
search-result-category-header-title N/A The title within the header of the category modal.
search-result-category-header-button N/A The close button within the header of the category modal.
search-result-category-close-button N/A The close button at the bottom of the category modal.
search-result-no-match N/A Empty state shown when a search phrase have 0 hits.

Search header

Part State part support Description
search-header-header N/A The header element of the search header.
search-header-subheader N/A The subheader element of the search header.
search-header-subheader-spaced N/A The subheader element of the search header that is used when multiple values are displayed within the subheader.
search-header-hits N/A Displays the amount of product hits for the current search phrase.

Sort by

Part State part support Description
sort-by N/A Similar to a facet item but specific to the sort-by element.

Swatch

Part State part support Description
swatch N/A Colour swatch used for thumbnail hints in the product cards and for colour values in the colour facet.

Custom font icons

The icons used in the web components can be customised by providing a URL to a .woff-file containing custom font glyphs. When providing custom font glyphs, all icons as specified below must be present in the file.

All font icons

Step by step guide

  1. Create the icons and save them in the SVG vector format. Do not use pixel based icons as they do not scale well.
  2. Replace the icons. Make sure all 74 ligature icons are provided, e.g. only replace the ones that custom icons are provided for.
  3. Create and host a .woff-file containing the custom icons. The creation of a .woff-file could for example be done using an application such as IcoMoon or any other suitable application. For applications that support loading icons as .json-files, the default icons can be loaded and viewed.
  4. Provide the custom icons by initialising eSales with the parameter iconUrl pointing to the .woff-file. For more information, see Script Initialisation.
    // init-esales-lifestyle.js
    esales.init({
    ...
    iconUrl: 'https://cdn.esalesdrivensite.com/custom-icons.woff',
    ...
    });
    
  5. Success!

Shadow part shim

As of June 2020, browsers facilitating roughly 70% of the global browser usage fully support CSS Shadow Parts. This includes the following browsers:

  • Firefox 76+
  • Chrome 81+
  • Safari 13.1 (13.4 iOS)

To support older browsers, with partial or no built in support, a custom built shim is included in the JavaScript library. The shim ensures that the Theming API V2 is compliant with the general component library browser support, while allowing styling using CSS Shadow Parts.

Shim limitations

  • Stylesheet resources using <link> must be decorated with the class esales-lifestyle-stylesheet, <link class="esales-lifestyle-stylesheet">.
  • Stylesheet resources using <link> must be retrievable via fetch(), hence correct CORS headers must be applied if necessary. This is applicable if the resource is hosted on a separate domain, such as a CDN.
  • Selectors above components are only evaluated when components re-render for performance reasons. For example, adding .active to the body will not take effect for the rule .active ::part(foo) until a component is re-rendered.

Last update: December 1, 2020
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE