Quick Start Guide

Follow these steps to help you get started with TwicPics in just a few minutes.


If you read this, chances are you already have a TwicPics account. If that's not the case, don't worry. You can easily create one here for free.

Setup your Image Source

Once signup is complete, TwicPics sets a domain for you like this - {your-subdomain}.twic.pics - which will be used to deliver all your images.

Let’s consider that your subdomain is "my-sub" (i.e. my-sub.twic.pics) for the rest of this guide.

From your back-office "Domains" section, you need to create a “Path” that you will point to an image source URL (where your images are stored).

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

Store only the highest-resolution version of each image you want to serve . TwicPics is designed around the concept of a single, high-resolution master image that’s used to generate as many derivatives (such as different sizes or crops) as your end-users need.

For instance, if your image source URL is https://my-company.com/images/ you can link the root path of your TwicPics’ custom subdomain to it.

Once done, your image https://my-company.com/images/my-image.png is accessible through TwicPics at https://my-sub.twic.pics/my-image.png.

For more info on your domain settings, please see the related documentation .


Now that your first setup is done, you can start using TwicPics to optimize your images.

TwicPics provides a frontend Script that works with a URL based API. In this way, TwicPics analyzes the CSS sizing context of your target image location and is DPR aware. Because TwicPics is 100% dynamic, your images automatically adapt to any responsive behavior implemented in your page.

The generated images are sized to the pixel and lazy-loaded. Which means your pages stay lightweight and load quickly.

Getting started

First, add the TwicPics Script to your page :

<script async defer src="https://<my-sub>.twic.pics/?v1"></script>
Replace my-sub with your own subdomain. You can find it in the "Domains" section of the back-office.


Then, whenever you want the Script to handle an image, simply specify a data-twic-src attribute like so:

img {
  display: block;
  object-fit: cover;

<!-- 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 of your TwicPics’ domain.

With the previous setup example:

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 derivative sizes from one device to another. For instance, you should get 600x600 images if you're 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 your background images in pretty much the same way:

.bg {
  width: 300px;
  height: 300px;
  background-size: cover;

<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 whether with object-fit property for the img elements or background-size for backgrounds. This is one of the strengths of TwicPics. If you have a look at the examples below, you'll find that images are not only resized but also automatically 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 is 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's see how you can use 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;
  <figure class="img-16-9">
    <img data-twic-src="image:<path_to_image>">

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

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

The informed developer could argue that that is a lot of derivatives to generate. True. In this kind of context you can take advantage of the step directive. This feature can be used globally or locally like in the example above.

What about native responsive images?

One of TwicPics' purposes is to free developers from the time and complexity of using picture elements and srcset attributes. But there are some use-cases where you'll need to / prefer to / have to / should use native responsive images. No problem. You're covered thanks to TwicPics URL API.

We even recommend using native responsive images combined with TwicPics API for images above the fold (or so called "critical images").

Let's take a big header at the top of a page as an example, you can write this kind of markup:


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

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

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

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

Note how the ratio expression syntax is combined with the transformation chaining approach to easily handle complex art-direction behaviors (i.e. cover=16:9/resize=500 ).

What's next?

We hope this guide has given you a better understanding of how to get the most out of TwicPics.

We can't let you go without one more thing. Why not taking advantage of the Script, the API and CSS together to deliver best-in-class UI/UX behaviors?

Let's say you want to mimic the LQIP (Low Quality Image Placeholder) made popular by Medium. It's ridiculously easy to do with TwicPics:

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

What happened here:

  1. We use the output=preview feature to deliver a very light blurry SVG preview of our picture as a background.
  2. We display the pixel-perfect image above when its ready thanks to TwicPics' script.

Now let's add some CSS:

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

img.twic-done {
  opacity: 1;

Thanks to TwicPics life-cycle (.twic-done class in this case), we apply CSS so that our beautiful image is loaded with a fade-in effect.

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

We can't wait to see what you do with TwicPics. Let us know if you find some creative new way to use the product!