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:
- Download the default stylesheet, available at
https://cdn.esales.apptus.com/integration/v1/esales-lifestyle-responsive.css
- Modify the stylesheet for the desired look-and-feel, following the specification in this section.
- Host the CSS-file on your domain.
- 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. - Add
disableResponsiveStyleSheet: true
as a property to the script initialisation. - 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. |
Breadcrumbs
Part | State part support | Description |
breadcrumbs | N/A | Breadcrumb list element. |
breadcrumb | Inactive | Breadcrumb list item element. |
breadcrumb-separator | N/A | Breadcrumb separator element. |
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. |
Navigation tree
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. |
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.

Step by step guide
- Create the icons and save them in the SVG vector format. Do not use pixel based icons as they do not scale well.
- Replace the icons. Make sure all 74 ligature icons are provided, e.g. only replace the ones that custom icons are provided for.
- 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. - 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',
...
});
- 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