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 Integrations

How to use Clerk.js to integrate Clerk.io without anything but HTML.

The most powerfull 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 a example. The following code lists the store's 3 most popular products:

<!-- List of products -->
<ul class="product-list" id="clerk-list">
  <!-- Clerk.js Block to be rendered -->
  <script
    class="clerk"
    type="text/x-clerk-template"
    data-target="#clerk-list"
    data-api="recommendations/popular"
    data-limit="3">
    
    <!-- Template used for each product -->
    <li class="product">
      <a href="{{ url }}">
        <img src="{{ image }}" title="{{ alt }}" />
        <h2>{{ name }}</h2>
        <div class="price">{{ money price }}</div>
        <button>Buy Now</button>
      </a>
    </li>
          
  </script>
</ul>
<!-- List of products -->
<ul class="product-list">
  <!-- Clerk.js Block to be rendered -->
  
    <!-- Template used for each product -->
    <li class="product">
      <a href="http://your-store.com/red-lightsaber">
        <img src="http://your-store.com/images/red-lightsaber.jpg" alt="Red Lightsaber" />
        <h2>Red Lightsaber</h2>
        <div class="price">1,495.95</div>
        <button>Buy Now</button>
      </a>
    </li>
  
    <!-- Template used for each product -->
    <li class="product">
      <a href="http://your-store.com/death-star-deluxe">
        <img src="http://your-store.com/images/death-star-deluxe.jpg" alt="Death Star Deluxe" />
        <h2>Death Star Deluxe</h2>
        <div class="price">999,999,999,999.95</div>
        <button>Buy Now</button>
      </a>
    </li>
  
    <!-- Template used for each product -->
    <li class="product">
      <a href="http://your-store.com/tie-fighter">
        <img src="http://your-store.com/images/tie-fighter.jpg" alt="Tie Fighter" />
        <h2>Tie Fighter</h2>
        <div class="price">195,000.95</div>
        <button>Buy Now</button>
      </a>
    </li>
  
</ul>

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

All the magic above is initiated by the script element having the class clerk. Immediately after being loaded, Clerk.js will scan the page source for any element with the class clerk (it doesn't have to be a script element - script elements just ensure that the browser doesn't render the template).

Then it reads the data- attributes of the element. Note that if the attribute value is not valid JSON it will just be treated as a string. 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 Clerk.io as request parameters.

When Clerk.io responds, the resulting products will be rendered using the template in the block body and be injected in to the DOM where the block is placed.

In this process, click-tracking is automatically added to each product.

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.

data-after-call

Name of the global function to handle the after-call event.

See Events for more details.

data-before-render

Name of the global function to handle the before-render event.

See Events for more details.

data-after-render

Name of the global function to handle the after-render event.

See Events for more details.

data-on-error

Name of the global function to handle the after-on-error event.

See Events for more details.

Pure HTML Integrations

How to use Clerk.js to integrate Clerk.io without anything but HTML.