TwicPics Native Quick Start Guide

Learn to integrate TwicPics Native images and videos optimization API in your web page.

Registration

If you read this, chances are you already have a TwicPics account. If you don't have one, you can easily create your account here for free.

Setup your Image Source

With your brand new account comes a subdomain akin to <sub>.twic.pics that should have been created during the onboarding process. All your media will be delivered through this domain from now on.

From your Workspace "Domains" section, you just have to create a “Path” that will point to an image source URL (a folder online where your images are stored).

The simplest possible path configuration is to point the root of your TwicPics domain to the root of your media server.

Store only the highest-resolution versions of your media . TwicPics is designed around the concept of a single, high-resolution source used to generate all the variants your end-users will ever need (different sizes, smart crops, etc) .

Suppose your media are located inside https://my-company.com/images/. You need to point the root path of your TwicPics subdomain to this source URL.

If you have an image located at https://my-company.com/images/logo.png then it can now be accessed through TwicPics at https://<sub>.twic.pics/logo.png.

For more informating regarding path configuration, please see the related documentation .

Usage

This quick setup done, you can now use TwicPics to optimize your media.

TwicPics provides a frontend Script that works in conjunction with a URL based API. This Script will analyze the CSS sizing context of your webpages and is also DPR aware. Because TwicPics is 100% dynamic, your images automatically adapt to any responsive behavior implemented in your HTML.

The generated images are sized to the pixel and lazy-loaded. Your pages stay lightweight and load in a snap.

Getting started

First, add the TwicPics Script to your page :

<script async defer src="https://<sub>.twic.pics/?v1"></script>

Replace <sub> with your own subdomain. You can find it in the "Domains" section of the back-office.

Basics

Whenever you want the Script to handle an image, simply use a data-twic-src attribute like so:

<style>
  img {
    display: block;
    object-fit: cover;
  }
</style>

<!-- with HTML attributes -->
<img data-twic-src="image:<path_to_image>" width="300" height="300" />

<!-- Same result with CSS -->
<img data-twic-src="image:<path_to_image>" style="width:300px; height:300px;" />

Please note how src turned into data-twic-src and how image: is used as a shortcut for your TwicPics domain.

Continuing with our example:


TwicPics Domain	`https//<sub>.twic.pics`
TwicPics Path	`/`
TwicPics Source URL	`https://my-company/images/`

A data-twic-src referencing image:logo.png will use https://my-company.com/images/logo.png as the source image.

TwicPics will account for the DPR of the current device when computing the sizes of images. This means you might get different variant sizes from one device to another. For instance, you should get 600x600 images if you are on a Retina screen.

By default, the Script will not take a DPR greater than 2 into consideration. This is what we recommend but you can alter this behavior, check the documentation .

TwicPics can also handle background images in pretty much the same way:

<style>
  .bg {
    width: 300px;
    height: 300px;
    background-size: cover;
  }
</style>

<div class="bg" data-twic-background="url(image:<path_to_image>)"></div>

Note how the background image is specified in the data-twic-background attribute rather than in CSS.

You also probably noticed that both examples make use of the cover CSS behavior be it with object-fit or background-size. TwicPics understands CSS and if you have a look at the examples below, you will find that images are not only resized but also cropped:

Feel free to inspect the results to see what TwicPics does under the hood.

Responsive Images

So far, we have only seen static and rather simple examples. The true power of TwicPics lies in how it handles more complex responsive designs.

A common approach nowadays is to think with aspect ratio in mind. One popular solution is the "aspect ratio padding trick".

Let us see how you can leverage this technique with TwicPics:

.img-16-9 {
  position: relative;
  width: 100%;
  height: 0;
  padding-top: calc(9 / 16 * 100%);
}

.img-16-9 > img {
  position: absolute;
  width: 100%;
  height: 100%;
  top: 0;
  left: 0;
  object-fit: cover;
}

<main>
  <figure class="img-16-9">
    <img data-twic-src="image:<path_to_image>" />
  </figure>
</main>

Your image is now responsive while preserving the given aspect ratio. Note how it is dynamically resized if you change the width of your window or the orientation of your device.

Using this technique allows you to easily tackle art direction and deliver jank-free page load. To learn more about Cumulative Layout Shift (CLS) and recent browser initiatives on the subject, we recommend that you read this article by Addy Osmani.

It can be a good idea to leverage the step directive to limit the number of variants generated. This feature can be used globally or locally like in the example above.

What about native responsive images?

A main goal of TwicPics is to free developers from the time and complexity of using picture elements and srcset attributes. Yet there are use-cases where you should continue using native responsive images. This is still possible by writing API requests.

We recommend using native responsive images for images above the fold (so called "critical images").

Let us consider a header at the top of a page, you could and should use markup like this:

<picture>
  <source
    media="(max-width: 767px)"
    srcset="
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=1:1/resize=300 300w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=1:1/resize=500 500w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=1:1/resize=700 700w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=1:1/resize=900 900w
    "
  />

  <source
    media="(min-width: 992px)"
    srcset="
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:4/resize=1000 1000w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:4/resize=1500 1500w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:4/resize=1900 1900w
    "
  />

  <source
    media="(min-width: 768px)"
    srcset="
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:9/resize=800   800w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:9/resize=1000 1000w,
      https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:9/resize=1200 1200w
    "
  />

  <img
    src="https://<sub>.twic.pics/my-source-image.jpg?twic=v1/cover=16:9/resize=1024"
  />
</picture>

Note how transformation chaining is used here so that ratios are explicit (like in cover=16:9/resize=500 ). Using this approach, you can tackle complex art-direction behaviors while maintaining readability.

What's next?

We hope this guide has given you a better understanding of how to get the most out of TwicPics, yet we can't let you go without one more treat!

Why not take advantage of the Script, the API and CSS at the same time and deliver best-in-class UI/UX behaviors?

Suppose you want to implement the LQIP (Low Quality Image Placeholder) technique made popular by Medium. With TwicPics, it is ridiculously easy:

<figure
  style="background-image: url(https://<sub>.twic.pics/<path_to_image>?twic=v1/output=preview)"
>
  <img data-twic-src="image:<path_to_image>" />
</figure>

What happens here?

We take advantage of the output=preview API to deliver a low-footprint, blurry preview of the image as a background.
We display a pixel-perfect image on top of it when it gets into view thanks to TwicPics Native.

Let us add some CSS:

img {
  opacity: 0;
  will-change: opacity;
  transition: opacity 1s linear;
}

img.twic-done {
  opacity: 1;
}

By using the loading lifecycle (and the twic-done class in this instance), we can use CSS so that the final image appears with a fade-in effect.

Here is an image gallery that makes use of this approach:

We can't wait to see what you will do with all that power. And please, let us know of all the creative ways in which you use TwicPics!

Guides