The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub.

This is site is only technical specification for developers.

You'll find comprehensive guides and documentation to help you start working with Clerk.io at our Help Center

Get Started    

Pure HTML Integration

The core feature of Clerk.js is the ability to embed any Clerk.io result into any website using nothing but HTML!

The easiest way to explain how is just with an example. The following code lists the store's 3 most popular products:

<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">

  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
</span>
<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">
	<!--
  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        <div class="price">{{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
  -->
  <ul class="product-list">
    <li class="product">
      <h2 class="product-name">Product Name #1</h2>
      
      <img src="/product/image/1.jpg" title="Product Name #1" />
      
      <div class="price">$111,11</div>
      <a href="/product/1">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #2</h2>
      
      <img src="/product/image/2.jpg" title="Product Name #2" />
      
      <div class="price">$222,22</div>
      <a href="/product/3">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #3</h2>
      
      <img src="/product/image/3.jpg" title="Product Name #3" />
      
      <div class="price">$333,33</div>
      <a href="/product/3">Buy Now</a>
    </li>
  </ul>
</span>

Thats all there is to it! No code! Easy!

Let's break down how Clerk.js renders this embed code:

  1. All the magic above is initiated by the span element having the class clerk. Immediately after being loaded, Clerk.js will scan the page source for any element with the class clerk.
  2. Then it reads the data- attributes of the element. An attribute can be a special attribute and will thus have the effect described in the list of special attributes below. All other data- attributes will be sent to the Clerk.io API as request parameters.
  3. When the Clerk.io API responds, the resulting products will be rendered using the template in the block body and be injected into the DOM where the block is placed.
  4. In this process, click-tracking is automatically added to each product.
  5. In case of an error, a report will be made to the console with all error details.

Below is the list of special attributes. All other attributes will be sent as request parameters.

Attribute
Behaviour

data-api

The API endpoint to be requested.

data-template

CSS selector for the template to be used (to avoid duplicating templates). If not present, the element body will be used.

If the starting character is @, the template will be loaded from Clerk.io using the remainder of the value as the template id.

data-target

CSS selector for where the products should be rendered. If not present, the products will be added to the DOM where the current element is.