---
title: 'TwicPics Native Quick Start Guide'
menuTitle: 'Native Quick Start Guide'
description: 'Learn to integrate TwicPics Native images and videos optimization API in your web page.'
category: 'guides'
position: 2
---

# TwicPics Native Quick Start Guide

<docs-page-description :description="description"></docs-page-description>

## 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](https://account.twicpics.com/signup).

<youtube id="aLkdMhyjIMA" :controls="false"></youtube>

## 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**.

<doc-alert type="warning">**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) .</doc-alert>

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.

<video autoplay muted loop><source src="https://assets.twicpics.com/docs/screencast-create-path-2.mp4" type="video/mp4"></video>

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`.

<doc-alert type="info">For more informating regarding path configuration, please see the [related documentation](/docs/essentials/path-configuration).</doc-alert>

## 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 :

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

<doc-alert type="info">Replace `<sub>` with your own subdomain. You can find it in the **"Domains"** section of the back-office.</doc-alert>

### Basics

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

```html
<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;" />
```

<doc-alert type="info">Please note how `src` turned into `data-twic-src` and how `image:` is used as a shortcut for your TwicPics domain.</doc-alert>

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.

<doc-alert type="info">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](/docs/essentials/native#global-configuration).</doc-alert>

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

```html
<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:

<code-pen id="zYKzeQG" title="TwicPics 1o1"></code-pen>

<doc-alert type="info">Feel free to inspect [the results](https://codepen.io/twicpics/pen/zYKzeQG?editors=1100) to see what TwicPics does under the hood.</doc-alert>

### 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:

```css
.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;
}
```

```html
<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](https://web.dev/optimize-cls/) by Addy Osmani.

<code-pen id="yLaXroX" title="TwicPics 1o1 (aspect ratio padding trick)"></code-pen>

<doc-alert type="info">It can be a good idea to leverage the `step` directive to limit the number of variants generated. This feature can be used [globally](/docs/essentials/native#step) or [locally](/docs/reference/native-attributes#data-twic-step) like in the example above.</doc-alert>

### 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](/docs/essentials/api).

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:

```html
<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>
```

<doc-alert type="success">Note how [transformation chaining](/docs/reference/transformations#chaining-transformations) is used here so that [ratios](/docs/reference/parameters#ratio) are explicit (like in `cover=16:9/resize=500`). Using this approach, you can tackle complex art-direction behaviors while maintaining readability.</doc-alert>

## 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](https://medium.com/). With TwicPics, it is ridiculously easy:

```html
<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?

1. We take advantage of the [`output=preview`](/docs/reference/transformations#output) API to deliver a low-footprint, blurry preview of the image as a background.
2. We display a pixel-perfect image on top of it when it gets into view thanks to TwicPics Native.

Let us add some CSS:

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

img.twic-done {
  opacity: 1;
}
```

By using the [loading lifecycle](/docs/essentials/native#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](https://codepen.io/twicpics/pen/jwGxZd?editors=1100) that makes use of this approach:

<code-pen id="jwGxZd" title="Responsive Flexbox Grid (with TwicPics LQIP)"></code-pen>

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!