Components

Product Tile

To display a product tile with just a basic product info (image, title and price), use the data-tipser-product-tile attribute.

<div
  data-tipser-product-tile
  data-tipser-product-id="57233dac89862012f8ec1001"
></div>

Attributes:

Attribute

Description

Type

Required

Default

data-tipser-product-id

Tipser product id

string

true

none

data-tipser-orientation

image and product details alignment

'horizontal' or 'vertical'

false

'vertical'

data-tipser-size

the size of the product tile

'small', 'medium' or 'large'

false

'medium'

data-tipser-class-name

custom CSS class name to apply

string

false

none

Product Listing

A larger, more detailed and better exposed product view, typically occupying the full width of the article. Allows the user to add the product to cart without opening the product dialog (which means less steps needed by the user to purchase the product). For products with variants, a variant selector is displayed, letting the user pick the variant before adding to cart.

<div data-tipser-product-listing data-tipser-product-id="5ba2334a781baa0001ccdf61"></div>

Attributes:

Attribute

Description

Type

Required

Default

data-tipser-product-id

Tipser product id

string

true

none

data-tipser-class-name

custom CSS class name to apply

string

false

none

Collection

Collection is a group of simple product tiles. Clicking on any title displays a product dialog with more product details and add to cart button. Products displayed in a collection are defined in app.tipser.com.

<div data-tipser-collection
    data-tipser-collection-id="5b2788909d25801adcb23f4f">
</div>

Tags with attribute data-tipser-cid will be replaced with collection component of given id (specified by the data-tipser-collection-id attribute).

To make the collection items smaller / larger use the data-tipser-img-size attribute with values small for smaller and large for lager product tiles. The default value for data-tipser-img-size attribute is medium. When changing the value to small you get slightly smaller product-cards:

<div
  data-tipser-collection
  data-tipser-collection-id="5b2788909d25801adcb23f4f"
  data-tipser-img-size="small"
></div>

If you'd like the collection of more than several products to take less space, you can display it as one-row only carousel component. To do that, please use data-tipser-carousel attribute.

<div
  data-tipser-collection
  data-tipser-collection-id="5b2788909d25801adcb23f4f"
  data-tipser-carousel
></div>

Cart Icon

To keep the user informed about the state of their shopping cart and make it possible to finalize the checkout process at any time, you can attach a live shopping cart icon on your page.

<div data-tipser-cart-icon></div>

By default the cart icon position is static. One common use case that we know about is "sticky" cart icon (that stays on the screen when scrolling), you can use the following CSS style to get this behavior:

.cart-icon {
  position: fixed;
  right: 0;
  top: 121px;
  background: #fff;
  padding: 10px;
  box-shadow: -2px 2px 7px rgba(0, 0, 0, 0.3);
  z-index: 10;
}

Product page

A full-sized product component to be used on a dedicated page.

<div 
    data-tipser-product-page
    data-tipser-product-id="5bc6e1c7df2ac60001158814">
</div>

Tags with attribute data-tipser-product-page will be replaced with the product page element. The value of the data-tipser-product-id attribute for a certain product can obtained from app.tipser.com.

Example:

📘

This component renders the same product view that is displayed inside the product modal.

📘

This component takes up a large part of the page, so it is recommended to place it on a dedicated subpage.

Store

The store component, activated by data-tipser-store tag, is the best way to present a group of collections. We recommend placing it on a dedicated page where sufficient space is available but the store component will try to adapt to the available space.

Before you insert the store on your page, make sure there is at least one collection created in your store, otherwise no content will be rendered. The store collections can be created using the app.tipser.com.

Insert the following HTML snippet in the place where you want the store to be rendered.

<div data-tipser-store></div>

📘

The Store element is best inserted as a top-level element on a separate page and should take the full content area for the optimal shopping experience.

Store menu display

You can choose between two ways of displaying the store menu on the mobile screens. The default one is a native dropdown. If you prefer to use the inline menu instead (the same one as is displayed on other screen sizes), add data-tipser-inline-mobile-menu attribute to the HTML snippet:

<div data-tipser-store data-tipser-inline-mobile-menu></div>

Cart Page

To display the contents of the shopping cart you can use the cart page component.

<div data-tipser-cart-page></div>

📘

To provide a path to your custom cart page, please define the cartUrl key in the customUrls config option.

Updating the browser's URL

By default, the store component saves the active collection in the browser's URL hash part (everything after the # symbol in the URL). It allows the users to bookmark the store page or share the URL with others (the same collection will be active in the store when opening the link). To opt-out of this behaviour (e.g. because it interferes with the routing system of your site), add the data-tipser-disable-deep-linking attribute.

<div data-tipser-store data-tipser-disable-deep-linking></div>

Checkout

Then use this HTML tag to render Checkout on your page.

<div data-tipser-checkout-page></div>

📘

To provide a path to your custom checkout page, please define the checkoutUrl and checkoutConfirmation key in the customUrls config option.

📘

This component takes up a large part of the page, so it is recommended to place it on a dedicated subpage.

Product List

A list of products specified by ids, rendered as product tiles.

<div
  data-tipser-product-list data-tipser-product-ids="5a8ac10d9d2580326ca4cf47,5a9735d99d25801620c3d3fc,5a8af4909d2580132ca4c1f9"
></div>

Attributes:

Attribute

Description

Type

Required

Default

data-tipser-product-ids

the list of Tipser product id's (comma separated)

string

true

none

data-tipser-class-name

custom CSS class name to apply

string

false

none


Modular Product

A modular product is a product that can be constructed from lower level components.

Below is an example HTML snippet that renders a modular product with an image, title, price and variant selector and buy button.

<div data-tipser-modular-product data-tipser-product-id="5bc6e1c7df2ac60001158814">
  <div data-tipser-modular-product-image></div>
  <div data-tipser-modular-product-title></div>
  <div data-tipser-modular-product-price></div>
  <div data-tipser-modular-product-variant-selector></div>
  <div data-tipser-modular-product-buy-button></div>
</div>

The complete list of HTML attributes related to modular product:

  • data-tipser-modular-product attribute is a marker for the top level element providing the product context (all the other elements need to be nested below it)

The list of all of the supported modular product subcomponents:

  • data-tipser-modular-product-title
  • data-tipser-modular-product-buy-button
  • data-tipser-modular-product-price
  • data-tipser-modular-product-image
  • data-tipser-modular-product-thumbnails
  • data-tipser-modular-product-availability-info
  • data-tipser-modular-product-variant-selector
  • data-tipser-modular-product-description
  • data-tipser-modular-product-similar-products
  • data-tipser-modular-product-style-with-products
  • data-tipser-modular-product-color-relations

Product Image

Displays the full-size version of the currently selected product image.

📘

The tag with data-tipser-modular-product-image attribute must have fixed width and height specified.

<div
   data-tipser-modular-product data-tipser-product-id="5bc6e1c7df2ac60001158814"
>
  <div data-tipser-modular-product-image style=“width:400px,height:500px”></div>
</div>
AttributeTypeDescriptionDefault
data-tipser-enable-swipeHTML booleanenables swipe functionality (recommended for touch devices)false
data-tipser-enable-arrowsHTML booleanshow left and right arrows for changing imagesfalse
data-tipser-enable-dotsHTML booleanshow slider bullet dotsfalse
data-tipser-class-namestringcustom CSS class name to applynone

Product Thumbnails

Displays the product thumbnails.

📘

The tag with data-tipser-modular-product-thumbnails attribute must have fixed width and height specified.

div data-tipser-modular-product data-tipser-product-id="5bc6e1c7df2ac60001158814">
  <div data-tipser-modular-product-thumbnails style=“width:400px,height:500px”></div>
</div>
AttributeTypePossible valuesDescriptionDefault
data-tipser-image-fitstring'contain' | 'cover'changes the background-size property'cover'
data-tipser-directionstring'vertical' | 'horizontal'changes the orientation of the thumbnails container'horizontal'
data-tipser-class-namestringcustom CSS class name to applynone



Modular Checkout

If you need more flexibility, you can use the data-tipser-modular-checkout tag. The children of this element will define a set of checkout modules to be displayed. For example, a children element with data-tipser-modular-checkout-products attribute (nested under the master element with data-tipser-modular-checkout attribute) will render the list of items that
are being purchased by the user.

A working example of the checkout view consisting of: items list, delivery address form and the payment form:

<div data-tipser-modular-checkout>
  <div data-tipser-modular-checkout-product-list></div>
  <div data-tipser-modular-checkout-customer-address-delivery></div>
  <div data-tipser-modular-checkout-payment></div>
</div>

Following modules can be nested within <div data-tipser-modular-checkout></div>:

Checkout Product List

This section displays a list of items in the current checkout.

<div data-tipser-modular-checkout-product-list></div>

Attributes:

attr name

description

type

values

default value

data-tipser-editable

should the product list be editable? (changing quantities and/or removing items)

HTML boolean

false

Checkout Customer Delivery Address form

This form accepts user's delivery address details.

📘

This component is only available for integrations using Stripe as the payment provider. In case of Klarna, data-tipser-modular-checkout-payment contains its own fields for entering delivery and billing address.

<div data-tipser-modular-checkout-customer-address-delivery></div>

attr name

description

type

values

default value

data-tipser-hide-submit-button

hides the "submit" button that collapses the form after filling it with correct data

HTML boolean

false

data-tipser-submit-behaviour

the behaviour of the form after submitting it

string

'collapse', 'none'

'collapse'

data-tipser-hide-use-as-billing-address-checkbox

hides the checkbox allowing to copy delivery address as billing addres

HTML boolean

false

Checkout Customer Billing Address form

This form accepts user's billing address details.

📘

This component is only available for integrations using Stripe as the payment provider. In case of Klarna, data-tipser-modular-checkout-payment contains its own fields for entering delivery and billing address.

<div data-tipser-modular-checkout-customer-address-billing></div>

attr name

description

type

values

default value

data-tipser-hide-submit-button

ides the "submit" button that collapses the form after filling it with correct data

HTML boolean

data-tipser-submit-behavior

he behavior of the form after submitting it

string

'collapse', 'none'

'collapse'

data-tipser-depends-on

lets you render the component depending on the delivery form being valid

string

'none', 'validDeliveryAddress'

'none'

Checkout Summary

A summary of the total costs resulting from the checkout (total cost, shipping cost, taxes, discounts, etc).

<div data-tipser-modular-checkout-summary></div>

Checkout Payment

A payment section, accepting user's payment input (e.g. credit card number). In case of Klarna integrations, this component will additionally contain delivery and billing address forms.

<div data-tipser-modular-checkout-payment></div>

attr name

description

type

values

default value

data-tipser-hide-pay-button

hides the "pay" button in Stripe payment provider form

HTML boolean

data-tipser-depends-on

lets you render the component depending on the delivery form being valid

string

'none', 'validDeliveryAddress'

'none'

Checkout Promotion Code

An element for entering promotion codes corresponding to Tipser campaigns (please contact your KAM to define one).

<div data-tipser-modular-checkout-promo-code></div>

Order Confirmation Page

A confirmation page displaying a summary of the completed order.

<div data-tipser-modular-checkout-order-confirmation></div>

Checkout Order Processing

A loading animation for checkout processing.

<div data-tipser-modular-checkout-order-processing></div>

Checkout Legal Terms

A text explaining legal terms of the purchase.

<div data-tipser-modular-checkout-legal></div>

API reference

All configuration supported by Tipser Script is listed below.

ParameterDefaultDescriptionExample
lang'en-US'a locale to be used by the Tipser content. Possible values: 'en-US', 'de-DE', 'fr-FR' and 'sv-SE'. More info at Language and Locale, Environment'de-DE'
env'prod'Tipser environment to be used by the Tipser content. Possible values: 'stage' and 'prod'. More info at Environment'stage'
defaultAddedToCartPopuptrueControls default Added To Cart Popup. It appears when user adds a product to the cart. It improves UX by highlighting the action and allowing to navigate quickly to the cart modal window.true or false
useDefaultErrorHandlertruewhen set to false and error happens, default message won't be displayedsee Adding onError handler
eventsHandlers{}the object of event handlers. See Event handlers{ onError: console.error.bind(console) }
modalUi{}Customization of Tipser Dialog. More info at Parameters for dialog customization{hideSimilarProducts : true}
primaryColor#333Hex color code, affecting eg. buy-button color and Cart indicator#5F9F9F
disableAnalyticsfalseIf set to true, all Tipser analytics requests will be blocked (no events to Analytics and stats.tipser.com will be sent)true

Event handlers

Event handlers can be passed as part of configuration. There is a number of event exposed by the Tipser Script that can be listened to programatically, such as technical events, shopping behavior, errors and analytics. You may hook in your event listener into Tipser Script via eventsHandlers option.

tipserScript.initialize("posId", {
  eventsHandlers: {
    onAddToCart: (payload) => {
      console.log("Hurray, you have added item to cart. ", payload.product);
      console.log("Your cart size is now. ", payload.cartSize);
    },
  },
});

Whenever an event occurs, Tipser Script will call your event listener, passing only one argument - payload - which will hold event data (different to each event type). Above example demonstrates how to listen to the add to cart event and log current cart size and newly added product. Currently supported handlers are: onAddToCart and onError.


onAddToCart

onAddToCart: (cartSize: number, product: TipserProductModel)
  • cartSize- property contains the cart size after a product has been added to the cart
  • product - is an object as well and representing the product which has been added to cart. The model of the product field is as follows.

TipserProductModel interface is as follows:

interface TipserProductModel {
  id: string;
  title: string;
  description: string;
  brand: string;
  images: any[];
  isInStock: boolean;
  deliveryTime: string;
  priceIncVat: PriceModel;
  deliveryCost: PriceModel;
  variants: TipserProductModel[];
  discountPriceIncVat: PriceModel;
  freeReturn: boolean;
}

onError

By default, in case of an unexpected error happening (connection issues or unhandled runtime exceptions), an error popup appears. If you want to disable that default error popup, set useDefaultErrorHandler option to false, and replace it by your own error handling by listening to error messages via onError event handler.

tipserScript.initialize("posId", {
  useDefaultErrorHandler: true,
  eventsHandlers: {
    onError: (error) => {
      console.log(error);
    },
  },
});

The payload of error event is as follows:

  • type: TipserElementError object

  • id: string

  • message: error message

  • stack: typical error stack of js error

The onError event handler is used with useDefaultErrorHandler config option. When that option is set to false (default to true) the error will not be shown on the screen.

❗️

This section requires simplification. It isn't clear how to use event handler with combination of this configuration.

onStockCountChange

This handler takes care of the edge case, when while in the checkout process and before payment, the stock count of an item in the cart becomes lower than the number of items in the cart. By default, in such a situation, we display an overlay with an information about the stock count change and the button for reloading the checkout. If you wish to customize this behaviour, you can use a callback onStockCountChange(items: CartItemModel[]) => void, which will prevent the default behavior.

Customizing the styles

Our e-commerce components are the "building blocks" designed to fit your page as much as possible. We created the styling in a way that delivers a nice look & feel from the start, but also allows you to change them easily to fit your unique sense of style. For example, all elements' font-family and font-size attributes are set to inherit them from the host page. If you need to change some other styles, please overwrite the CSS classes corresponding to the elements that you customize (listed below).

Product Card

The Product Card is an item used for displaying a single tile in a Collection or Store component, among others. The font-family used in the description section of the Product Card is inherited from your website's styles, and the font-size is expressed in the relative em units controlled in .te-product-card class. The default value used there is 12px, which you can easily change by adding to your CSS the following style:

.te-product-card {
  font-size: 14px;
}

All the description elements (product name, brand and price) will become bigger / smaller according to the value you specify in the px unit. If you wish to change single description element, please use its specific class names:

.te-product-card-name

.te-product-card-brand

.te-product-card-price

and:

.te-product-card-sales-price

.te-product-card-price-regular-price

for products on sale.

Cart

The Cart component with the cart icon can be placed anywhere on your website. (It is highly advisable to place it in your navigation element among other icons such as search, home etc.) However, if you want to keep it visible at all times, attached to the right side of the viewport, you can use these styles:

.cart-icon {
  position: fixed;
  right: 0;
  top: 121px;
  background: #fff;
  padding: 10px;
  box-shadow: -2px 2px 7px rgba(0, 0, 0, 0.3);
  z-index: 10;
}

Adding Primary color

If you'd like to unify our design with your own color-theme, you can use our primary-color configuration option. If your primary color is a bright one, you might also want to change the text color of the elements that use the primary color as the background, e.g. add to cart buttons. For example in buttons by default the color we use is white.

/* if your primary color is bright,
    you may also consider changing the text color for elements like buttons: */
.te-button-text {
  color: #333;
}

If you'd like to change other elements' color as well, please use specific classes to override the styles.

Starter projects

A working example of a page based on Tipser Elements can be found under Tipser Script Bootstrap page..

The code of that page is available as a GitHub repo: Tipser Script Bootstrap project. Feel free to clone it and run it locally!