---
title: 'TwicPics Native'
menuTitle: 'Native'
description: 'Learn how to use TwicPics Native to benefit from context-aware media optimization in your web pages.'
category: 'essentials'
position: 4
---

# TwicPics Native

TwicPics Native enables lazy loading together with automatic and dynamic sizing of your images and videos. Lightweight and non-intrusive, this small piece of JavaScript only handles elements you specifically marked beforehand.

## Setup

### Installation

You simply have to include the TwicPics script from your own [domain](/docs/essentials/domain-configuration) in your webpage.

```html
<!-- TwicPics domain -->
<script async defer src="https://<subdomain>.twic.pics/?v1"></script>

<!-- Custom domain -->
<script async defer src="https://<custom-domain>/?v1"></script>
```

<doc-alert>You can find your domain in your workspace domains list:<illustration src="/docs/getting-started/integration/integration-01.png"></illustration></doc-alert>

That's it, you're all set!

### Integration

If you want TwicPics Native to handle the source of an `img` or `video` element, the poster of a `video` element, or the background image of any DOM element, simply specify a `data-twic-src`, `data-twic-poster` or `data-twic-background` attribute respectively:

#### Images

```html
<!-- Without TwicPics -->
<img src="https://my-assets.storage.com/image.jpeg" />

<!-- With TwicPics -->
<img data-twic-src="media:<image-path>/image.jpeg" />
```

#### Background images

```html
<!-- Without TwicPics -->
<div
  style="background-image: url('https://my-assets.storage.com/image.jpeg');"
></div>

<!-- With TwicPics -->
<div data-twic-background="url('media:<image-path>/image.jpeg')"></div>
```

#### Video posters

```html
<!-- Without TwicPics -->
<video poster="https://my-assets.storage.com/image.jpeg"></video>

<!-- With TwicPics -->
<video data-twic-poster="media:<image-path>/image.jpeg"></video>
```

#### Videos

```html
<!-- Without TwicPics -->
<video autoplay loop muted playsinline>
  <source src="https://my-assets.storage.com/video.webm" type="video/webm" />
  <source src="https://my-assets.storage.com/video.mp4" type="video/mp4" />
</video>

<!-- With TwicPics -->
<video data-twic-src="media:<video-path>/video.mp4"></video>
```

<doc-alert>You can [read the "Video optimization" guide](/docs/guides/video-optimization) for more information on optimizing videos in your HTML pages.</doc-alert>

<doc-alert type="info">Please note how `src` and `poster` turned into `data-twic-src` and `data-twic-poster` and how the background image is now specified in the `data-twic-background` attribute rather than in CSS.</doc-alert>

You can see that the value of the `data-twic-*` attributes is of the form `media:<path>/<asset-name>`, where:

- `media:` is an alias of your TwicPics domain,
- and `<path>` is a path of your TwicPics domain, that points to the Source URL of your assets.
  <doc-alert>You can find a path in your domain paths list.</doc-alert>

So, in each example shown above, the asset URL will be:

- `https://<your-twicpics-domain>/<image-path>/image.jpeg` in the case of an image,
- or `https://<your-twicpics-domain>/<video-path>/video.mp4` in the case of a video.

But TwicPics Native will make sure the media is optimized properly based on the user's context: it will generate the proper [API request](/docs/essentials/api) for you, e.g. `https://<your-twicpics-domain>/<image-path>/image.jpeg?twic=v1/resize=300`.

<doc-alert>[Check out these Codepen demos](#codepen-demos) to get a good idea of ​​how TwicPics Native manipulates the DOM to generate optimized media according to the user's context.</doc-alert>

## Dynamic Behaviour

TwicPics Native will only issue an API request and load your image when the corresponding element becomes visible, so everything is lazy-loaded by default, ensuring a fast initial page load.

You don't have to write any code. Everything is controlled declaratively using HTML attributes and CSS properties. Feel free to browse the [TwicPics Native attributes reference](/docs/reference/native-attributes) for more information.

### Lazy Loading

By default, the Script will load marked images only when needed. It will wait for an element to come into view before loading its source, poster or background images. This will help tremendously when it comes to the initial page load.

Sometimes, however, you may need images to be loaded in bulk, like in the case of a slideshow. In such a case, you can mark a container as a **view**:

```html
<div data-twic-view>
  <!-- content -->
</div>
```

Every marked element inside the container will be loaded as soon as the container itself comes into view.

If, for any reason, you wish to disable lazy loading entirely, simply mark the _body_ of your page as a view:

```html
<body data-twic-view>
  <!-- no lazy loading! -->
</body>
```

### DOM Manipulation

TwicPics Native is always observing changes in your document:

- it will detect newly inserted elements with a `data-twic-src`, `data-twic-poster`, `data-twic-background`, or `data-twic-view` attribute
- it will react whenever a TwicPics [attribute](/docs/reference/native-attributes) is modified
- it will re-assess image and video sizes if dynamic changes occur in your layout

### Loading Lifecycle

TwicPics Native happens to tag elements with specific classes whenever images are loaded under the hood. This is especially useful if you want to apply a specific CSS effect to images that are being loaded (like a fade-out/fade-in animation) or if you wish to visually highlight errors during development (like coloring problematic elements in red).

Here are the classes the Script will mark elements with:

- `twic-loading` when an `img` or `video` source is being loaded
- `twic-done` when an `img` or `video` source has been loaded
- `twic-error` when an error occurred while loading an `img` or `video` source
- `twic-poster-loading` when a `video` poster is being loaded
- `twic-poster-done` when a `video` poster has been loaded
- `twic-poster-error` when an error occurred while loading a `video` poster
- `twic-background-loading` when at least one of the background images of an element is being loaded
- `twic-background-done` when all background images of an element have been loaded
- `twic-background-error` when an error occurred while loading one of the background images

## Global Configuration

TwicPics Native can be configured by adding specific parameters to the library URL. All parameters come with a default value that should suit most users.

### anticipation

_Default value_: `0.2` (_any value that is not a number will be ignored_)

TwicPics Native will lazy-load media by default. To avoid too abrupt a transition with elements appearing into view and then media very obviously loading afterwards, TwicPics Native will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by `anticipation`.

With the default of `0.2` and for a viewport 800 pixels wide per 600 pixels high, TwicPics Native will consider as visible any element within a rectangle going from coordinates `(-160,-120)` to coordinates `(960,720)`. You could set `anticipation` to `1` and anticipate lazy loading by an entire screen: the rectangle where elements are considered visible would then go from `(-800,-600)` to `(1600,1200)`.

```html
<!-- anticipate lazy-loading by half a screen -->
<script async defer src="https://sub.twic.pics/?v1&anticipation=0.5"></script>

<!-- anticipate lazy-loading by an entire screen -->
<script async defer src="https://sub.twic.pics/?v1&anticipation=1"></script>
```

### class

_Default value_: `"twic"`

In the rare occurrence where `twic` is already in use on your page and you wish to avoid any potential collision, you can use this _script parameter_ to change `twic` into something else entirely.

<doc-alert type="warning">Note that every occurrence of `twic` must be replaced with whatever name you set this _script parameter_ to.</doc-alert>

So, the following configuration:

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

implies that:

- [attributes](/docs/reference/native-attributes) names are changed:
  - `data-twic-background` becomes `data-batman-background`
  - `data-twic-background-*` attributes become `data-batman-background-*`
  - `data-twic-bot` becomes `data-batman-bot`
  - `data-twic-focus` becomes `data-batman-focus`
  - `data-twic-poster` becomes `data-batman-poster`
  - `data-twic-poster-*` attributes become `data-batman-poster-*`
  - `data-twic-src` becomes `data-batman-src`
  - `data-twic-src-*` attributes become `data-batman-src-*`
  - `data-twic-step` becomes `data-batman-step`
  - `data-twic-transform` becomes `data-batman-transform`
- [views](/docs/essentials/native#lazy-loading) should be marked with `data-batman-view` rather than `data-twic-view`
- [lifecycle](/docs/essentials/native#loading-lifecycle) class names are changed:
  - `twic-loading` becomes `batman-loading`
  - `twic-done` becomes `batman-done`
  - `twic-error` becomes `batman-error`
  - `twic-poster-loading` becomes `batman-poster-loading`
  - `twic-poster-done` becomes `batman-poster-done`
  - `twic-poster-error` becomes `batman-poster-error`
  - `twic-background-loading` becomes `batman-background-loading`
  - `twic-background-done` becomes `batman-background-done`
  - `twic-background-error` becomes `batman-background-error`

### max-dpr

_Default value_: `2` (_any value that is not a number will be ignored_)

TwicPics Native will take the [Device Pixel Ratio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio) of the current device into consideration when determining the sizes of media to load. While this is the best approach in theory, it may clutter the bandwidth of portable devices with a high DPR but a fairly small screen surface relatively.

By default, the Script will not take a DPR greater than `2` into consideration. If the DPR of the device is higher than `2`, the Script will assume it to be `2`.

To alter this behaviour, change the value of `max-dpr`:

- you can lower it (for instance by setting it to `1`, effectively ignoring the DPR altogether)
- or you can be more permissive (for instance by setting it to `3` or `4`)

```html
<!-- ignore DPR -->
<script async defer src="https://sub.twic.pics/?v1&max-dpr=1"></script>

<!-- handle DPR up to 4 -->
<script async defer src="https://sub.twic.pics/?v1&max-dpr=4"></script>
```

### path

_Default value_: `""`

TwicPics Native will prepend all your TwicPics image paths with the string provided through `path`. This is especially useful to easily switch from one environment to another (like between a staging and a production environment).

Let us take the following domain configuration as an example:

| path       | source images URL                 |
| ---------- | --------------------------------- |
| `/staging` | `https://staging.my-company.com/` |
| `/prod`    | `https://www.my-company.com/`     |

```html
<!-- targets https://staging.my-company.com/ -->
<script async defer src="https://sub.twic.pics/?v1&path=staging/"></script>

<!-- targets https://www.my-company.com/ -->
<script async defer src="https://sub.twic.pics/?v1&path=prod/"></script>
```

The following image element:

```html
<img data-twic-src="image:asset.jpg" />
```

will target

- `https://staging.my-company.com/asset.jpg` if `path` is set to `staging`
- `https://prod.my-company.com/asset.jpg` if `path` is set to `prod`

<doc-alert type="warning">The value of `path` is added "as-is", so you have to be extra-careful with slashes and how you handle them. If all your `image:` URLs start with a slash, like `image:/asset.jpg` then `path` should not end with one. If, however, you do not have a leading slash in your `image:` URLs, as in `image:asset.jpg`, then `path` should end with a slash.</doc-alert>

### step

_Default value_: `10` (_any value that is not a number will be ignored_)

<doc-alert>The default step for <nuxt-link to="/docs/guides/video-optimization">videos</nuxt-link> is 100. Any values below will be ignored.</doc-alert>

To avoid requesting too may variants of the same medium (as could happen in the case of `width: 100%` elements for instance), TwicPics Native will round the width of media to the closest multiple of `step`. The height will then be computed so as to respect the original aspect ratio.

For instance, with the default of `10`, if the Script is told by CSS the size of an element is 334x146, it will round it down to 330x144. Alternatively, for an element that is 336x222, it will round the size up to 340x225.

You can change this value to get as close or as far from a pixel-perfect resizing as desired:

- lowering it to `5` would potentially double the number of variants requested,
- lowering it to `1` would be pixel-perfect all the time,
- adjusting it up to `1000` would greatly reduce the number of variants but would stress the scaling algorithms of browsers more.

Note that the stepping value can still be overridden on a per-element basis using the [`data-twic-step`](/docs/reference/native-attributes#data-twic-step) attribute.

```html
<!-- Pixel perfect -->
<script async defer src="https://sub.twic.pics/?v1&step=1"></script>

<!-- Less variants -->
<script async defer src="https://sub.twic.pics/?v1&step=50"></script>
```

## Codepen demos

Take a look at these Codepen demos to see TwicPics Native in action:

- [Image optimization demo](https://codepen.io/twicpics/pen/poQQypq)
- [Background image optimization demo](https://codepen.io/twicpics/pen/NWEErvZ)
- [Video poster optimization demo](https://codepen.io/twicpics/pen/eYQQzQv)
- [Video optimization demo](https://codepen.io/twicpics/pen/BaGRZwQ)