# TwicPics Complete Documentation

This document contains the complete TwicPics documentation in a single file for LLM training and reference.


---

# Getting started

## Why TwicPics?

# Why TwicPics?

## The problem

Websites are heavier than ever and the main culprits are images and videos. They eat up network bandwidth and increase the time visitors spend waiting for pages to load. Every tenth of a second reduces the overall conversion rate and dramatically impacts revenue.

With a wide range of devices, screen sizes, and pixel densities to support, tailoring images and videos is extremely challenging. Depending on the approach, it can complicate server-side architectures by an order of magnitude, make for convoluted deployment strategies, or just kill client-side performance.

This is where TwicPics comes in.

## The solution

TwicPics is a **Responsive Media Service Solution** (SaaS). It offers on-demand responsive image and video generation combined with a smart and unobtrusive drop-in replacement for the native `<img>`, `<picture>`, and `<video>` elements. All powered by a no-nonsense and testable [URL-based API](https://www.twicpics.com/docs/reference/transformations).

### Context-aware optimization

TwicPics acts as a media proxy. It requests your _master_ image or video from your web server, cloud storage, or DAM, then generates a **device-adapted version** delivered directly to the end user **from the closest delivery point** available.

<illustration src="docs/how-it-works-timeline.png" width="2154" height="502" alt="How It Works Timeline" placeholder="none"></illustration>

As a developer, this means you only deal with the high-resolution version of your assets, while end users receive **optimized** and **perfectly sized** variants.

<doc-details title="Show me an example">
Let's consider a full-width banner.</br></br>
A Brazilian tourist roaming the streets of Paris with an iPhone will fetch a <span class="font-medium">750px</span> wide, <span class="font-medium">33kB</span>, and <span class="font-medium">JPEG</span> image from one of our two delivery points in the French capital. The same person, now using Chrome on a MacBook back in their home country, will fetch a <span class="font-medium">1440px</span> wide, <span class="font-medium">114kB</span>, <span class="font-medium">WebP</span> image from our delivery point in São Paulo or in Rio de Janeiro, whichever is the closest.</br></br>
Widths, and thus file sizes, would be different if the iPhone was in landscape mode, if Chrome did not cover the whole screen of the MacBook, or if the MacBook had a retina display. TwicPics takes everything into consideration: orientation, dimensions on screen, pixel density, and much more!
</doc-details>

### Designed for Developers

TwicPics services fall into two categories: **client libraries** and a **URL-based API**.

Client libraries include:

- [TwicPics Components](https://www.twicpics.com/docs/essentials/components) _(recommended)_ — the TwicPics Components bring image and video best practices out of the box to your favorite front-end JavaScript framework.
- [TwicPics Native](https://www.twicpics.com/docs/essentials/native) — for native HTML/JS integration.

After [setting up your account](https://www.twicpics.com/docs/getting-started/setup), integrate one of our client libraries to benefit from context-aware optimizations for your media. The libraries understand the end user's device, connection, and CSS. They will **automatically form API requests** so that your assets are **perfectly adapted to the context** of your users.

You will rarely need to write API requests by hand. It will likely only happen when you can't rely on JavaScript context-aware optimization (emails, native apps, etc.)

## Features

<features-list :items="features"></features-list>

In the next section, see how to set up your account before integrating TwicPics into your website.

---

## Setup

# Account setup

To optimize your media with TwicPics, you first need an account. If you don't already have one, you can easily [register for free](https://account.twicpics.com/signup).

Once your account is successfully created, follow these steps to set it up:

1. [Create a workspace](https://www.twicpics.com/docs/getting-started/setup#create-a-workspace)
2. [Create a domain](https://www.twicpics.com/docs/getting-started/setup#create-a-domain)
3. [Create a path](https://www.twicpics.com/docs/getting-started/setup#create-a-path)
4. [Make your first request](https://www.twicpics.com/docs/getting-started/setup#make-your-first-request)

<doc-alert>These steps must be completed to integrate TwicPics into your website.</doc-alert>

## Create a workspace

A workspace allows you to **collaborate with your team on a dedicated project**. Having a workspace is required to [create a domain](https://www.twicpics.com/docs/getting-started/setup#create-a-domain) that will deliver your optimized assets.

Once logged into your account, click the "New workspace" or "Create workspace" button:

<illustration src="docs/setup/setup-01.png" width="2880" height="1642" caption="Dashboard interface upon the first login to the TwicPics back office."></illustration>

You will be asked to enter a name for your workspace:

<illustration src="docs/setup/setup-06.png" width="2086" height="1352" caption="Interface for creating a workspace."></illustration>

After setting up your workspace, you can [create a domain](https://www.twicpics.com/docs/getting-started/setup#create-a-domain).

## Create a domain

It's time to create your first domain.

A domain is the host that will **deliver your optimized media** and is required to [create one or more paths](https://www.twicpics.com/docs/getting-started/setup#create-a-path) that will know where to fetch your original assets.

Depending on your needs, you can choose between two domain types:

- [Create a TwicPics domain](https://www.twicpics.com/docs/getting-started/setup#create-a-twicpics-domain) — your optimized media will be served from a TwicPics domain (i.e. twic.pics), using the TwicPics CDN.
- [Create a custom domain](https://www.twicpics.com/docs/getting-started/setup#create-a-custom-domain) — your optimized media will be served from your own domain, using the TwicPics CDN. Note that only [Business and Enterprise plans](https://www.twicpics.com/pricing) can use a custom domain.

<doc-details title="What are the benefits of creating a domain?">
Media retrieved from a TwicPics domain get the following advantages:
<features-list :items="features"></features-list>
That's only the tip of the iceberg! Serving your media from a TwicPics domain enables you to use the full power of our API: use it to add <a href="/docs/essentials/path-configuration#source-authentication">secure access to your images</a>, add <a href="/docs/essentials/path-configuration#overlay">watermarking</a>, or implement <a href="/docs/essentials/path-configuration#default-manipulation">default transformations</a>.
</doc-details>

### Create a TwicPics domain

By creating a TwicPics domain, your optimized media will be served from a TwicPics domain, using the TwicPics CDN.

A TwicPics domain takes the form of `https://<subdomain>.twic.pics` where `<subdomain>` is a subdomain of your choice, generally the name of your company (e.g. `https://my-company.twic.pics`).

To create a TwicPics domain, click the "Create a TwicPics domain" button displayed on your dashboard interface:

<illustration src="docs/setup/setup-02.png" width="2880" height="1642" caption="Dashboard interface after creating your first workspace."></illustration>

Then, set a subdomain for your TwicPics domain:

<illustration src="docs/setup/setup-04.png?v=2" width="2088" height="1148" caption="Interface for creating a TwicPics domain."></illustration>

Once you have successfully created your TwicPics domain, [create a path](https://www.twicpics.com/docs/getting-started/setup#create-a-path) to complete your setup.

### Create a custom domain

By creating a custom domain, your optimized media will be served from your own domain, using the TwicPics CDN. Only [Business and Enterprise plans](https://www.twicpics.com/pricing) can use a custom domain.

<doc-alert>Connecting your domain to the TwicPics CDN will require adding two CNAME records.</doc-alert>

A custom domain takes the form of `https://<subdomain>.<domain>.com`, using a domain that you own (e.g. `https://media.my-domain.com`).

To create a custom domain, open the drop-down menu next to the "Create a TwicPics domain" button, displayed on your dashboard interface. Then click the "Create a custom domain" item:

<illustration src="docs/setup/setup-03.png" width="2880" height="1642" caption="Dashboard interface after creating your first workspace."></illustration>

You will be asked to fill in your domain:

<illustration src="docs/setup/setup-05.png" width="2074" height="1160" caption="Interface for creating a custom domain."></illustration>

Once you have successfully created your custom domain, [create a path](https://www.twicpics.com/docs/getting-started/setup#create-a-path) to complete your setup.

## Create a path

A [domain](https://www.twicpics.com/docs/getting-started/setup#create-a-domain) path points to a **Source URL**, a storage from which your original assets will be retrieved.

A **Source URL** can be your web server, cloud storage, DAM, PIM, or whatever accessible HTTP resource.

<doc-alert>If your media are spread over several storage spaces, you can create a path for each of them. This means your domain can contain as many paths as you want.</doc-alert>

Associated with your domain, whether it is a [TwicPics domain](https://www.twicpics.com/docs/getting-started/setup#create-a-twicpics-domain) or a [custom domain](https://www.twicpics.com/docs/getting-started/setup#create-a-custom-domain), a path is part of the **output URL** from which your optimized media will be served, e.g. `https://<subdomain>.twic.pics/<path>/image.jpeg`.

<doc-details title="Show me an example">Let’s say one of your **Source URL** is `https://media.my-company.com/`. The simplest path creation would be to point this **Source URL** to the root of your domain:<table><tr><th>Domain</th><th>Path</th><th>Source URL</th></tr><tr><td>`https://<subdomain>.twic.pics`</td><td>`/`</td><td>`https://media.my-company.com/`</td></tr><tr><td>`https://<custom-twicpics-domain>`</td><td>`/`</td><td>`https://media.my-company.com/`</td></tr></table>Then, your image `https://media.my-company.com/product.jpeg` would be accessible from the **output URL** `https://<subdomain>.twic.pics/product.jpeg` or `https://<custom-twicpics-domain>/product.jpeg` in case of a custom domain.
</doc-details>

To create a [domain](https://www.twicpics.com/docs/getting-started/setup#create-a-domain) path, click the "Create path" button from your dashboard:

<illustration src="docs/setup/setup-07.png" width="2074" height="1160" caption="Dashboard interface after creating your first domain."></illustration>

You will be asked to:

1. **Choose between an `image path` or a `video path`**, depending on the type of media to optimize. Note that video paths are only accessible to [Business and Enterprise plans](https://www.twicpics.com/pricing).
2. [Give a name to your path](#give-a-name-to-your-path).
3. **Enter a Source URL** to define your original assets storage.

<illustration src="docs/setup/setup-08.png" width="2088" height="1208" caption="Interface for creating a domain path."></illustration>

### Give a name to your path

You don't have to give a name to an `image path`. In this case, your path will automatically point your Source URL to the root of your domain (`/`):

<doc-alert>For obvious reasons, this approach is only available for one path per domain.</doc-alert>

| Domain                             | Path | Source URL                      |
| :--------------------------------- | :--- | :------------------------------ |
| `https://<subdomain>.twic.pics`    | `/`  | `https://media.my-company.com/` |
| `https://<custom-twicpics-domain>` | `/`  | `https://media.my-company.com/` |

You can also name your paths after the type of your original media:

| Domain                             | Path      | Source URL                                   |
| :--------------------------------- | :-------- | :------------------------------------------- |
| `https://<subdomain>.twic.pics`    | `/media/` | `https://media.my-company.com/web/`          |
| `https://<custom-twicpics-domain>` | `/logos/` | `https://media.my-company.com/images/logos/` |

As for `video paths`, they work just like image paths, except they **must start with the word `video`**, no matter what comes next:

| Domain                          | Path               | Source URL                             |
| :------------------------------ | :----------------- | :------------------------------------- |
| `https://<subdomain>.twic.pics` | `/video/`          | `https://media.my-company.com/videos/` |
| `https://<subdomain>.twic.pics` | `/videos/`         | `https://media.my-company.com/videos/` |
| `https://<subdomain>.twic.pics` | `/video-products/` | `https://media.my-company.com/videos/` |

### Apply path options

Please refer to the [path options](https://www.twicpics.com/docs/essentials/path-configuration#path-options) section if you need advanced path features. You will see for example how to:

- [authenticate to a secure storage](https://www.twicpics.com/docs/essentials/path-configuration#source-authentication),
- [define a fallback image URL](https://www.twicpics.com/docs/essentials/path-configuration#image-fallback-url),
- or [apply default transformations](https://www.twicpics.com/docs/essentials/path-configuration#path-options).

## Make your first request

At this point, you should be ready to test your setup by making your first request through TwicPics.

Depending on your setup, you should be able to request one of your images by filling your browser address bar with a URL of this format:

```curl
https://<your-twicpics-domain>/<your-path>/<your-image-filename>
```

And make your first transformation thanks to the **URL-based API**:

```curl
https://<your-twicpics-domain>/<your-path>/<your-image-filename>?twic=v1/resize=200
```

It's now time to proceed with integrating TwicPics on your website!

---

## Integration

# Integration

Now that you’ve [set up your account](https://www.twicpics.com/docs/getting-started/setup) and discovered what are [workspaces](https://www.twicpics.com/docs/getting-started/setup#create-a-workspace), [domains](https://www.twicpics.com/docs/getting-started/setup#create-a-domain), and [paths](https://www.twicpics.com/docs/getting-started/setup#create-a-path), let’s see how to integrate TwicPics into your website or apps.

## Components vs. Native vs. API

Depending on your needs and technical environment, you can choose one of our client libraries to integrate TwicPics into your project or directly use TwicPics' URL based-API:

1. **[TwicPics Components](#twicpics-components)** — If your website or app is powered by a JS framework such as React, Vue.js, Svelte, Angular or a meta-framework such as Next.js, Nuxt, Gatsby, Sveltekit, TwicPics Components are the option you should consider.
2. **[TwicPics Native](#twicpics-native)** — You're working on a native HTML/CSS/JS frontend integration and want to delegate image sizing complexity to TwicPics. This is the best option for you.
3. **[TwicPics URL-based API](#url-based-api)** — You want to keep control of your frontend integration or have a specific use case where Javascript is not an option, then you can take advantage of the TwicPics URL-based API.

<doc-details title="What's the difference between TwicPics Components and TwicPics Native?">The TwicPics Components embed our vanilla JS library as part of their operation. So, whether you use the TwicPics Components with your frontend JS framework or directly use TwicPics Native in your HTML pages, you will benefit from context-aware optimizations for your media, e.g. automatic resizing, lazy-loading, or DPR management.
<br/><br/>However, **the TwicPics Components are much more powerful!** They provide optimizations to make your integration work even more straightforward:<features-list :items="component-features"></features-list>
</doc-details>

## TwicPics Components

**TwicPics Components** is a **collection of web components** that make it dead easy to unleash the power of TwicPics in your projects.

Whether you need to display a content image, showcase a short video, or ensure optimal performance with _Large Contentful Paint_ (LCP) and _Cumulative Layout Shift_ (CLS) care, TwicPics Components has you covered.

TwicPics Components provides smart drop-in replacements for the `<img>`, `<video>`, and `<picture>` tags.

<illustration src="docs/all-components.png" width="1050" height="351" alt="TwicPics Components" placeholder="none"></illustration>

The components are available for React, Next.js, Gatsby, Vue.js, NuxtJS, Agular, Svelte, SvelteKit, React Native, Flutter, and Web components.

→ [Continue with TwicPics Components](https://www.twicpics.com/docs/essentials/components)

## TwicPics Native

To take advantage of **TwicPics Native**, you must integrate the TwicPics vanilla JS script to optimize your media in your HTML pages.

TwicPics Native is reactive. It manipulates the DOM in real-time based on the user's context: it allows lazy loading together with the automatic and dynamic optimization of your assets according to your CSS rules, the browser, and the bandwidth.

Lightweight and non-intrusive, this small piece of JavaScript only handles elements you specifically marked beforehand thanks to its `data-twic-*` HTML attributes.

→  [Continue with TwicPics Native](https://www.twicpics.com/docs/essentials/native)

## TwicPics URL-based API

**TwicPics URL-based API** is the first layer on top of the TwicPics processing engine. It offers dozens of transformations and unique features to manipulate your visual assets manually. Whether you want to crop, resize, flip, turn, trim, colorize, format, or zoom, you'll find all the tools you need to tailor your images and videos.

→  [Continue with TwicPics API](https://www.twicpics.com/docs/essentials/api)

---


---

# Essentials

## Domain Configuration

# Domain Configuration

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

A domain is a collection of paths. Domain paths map two URLs:

- **An output URL** — where optimized assets will be served from
- **A source URL** — the storage where the media will be retrieved from

Taking the example of the `subdomain.twic.pics` domain:

- If `/` points to `https://media.company.com/`
- Then `https://subdomain.twic.pics/image.png` will point to `https://media.company.com/image.png`.

## TwicPics domains

In each workspace domain section, you can configure a `subdomain` under the TwicPics domain:

<illustration width="2092" height="928" src="docs/createTwicPicsDomain-002.png" caption="Create a TwicPics domain"></illustration>

You can choose any `subdomain` you like, pending availability.

Example:  `https://mycompany.twic.pics`

## Custom domains

You can set up **custom domains of your own** (using custom CNAME).

Example: `https://assets-subdomain.yourcompany.com`

### Requirements

Connecting your domain requires adding **two CNAME records**.

- Use a domain that you own
- Use a sub-domain like `media.mydomain.com`
- Root domains, e.g. `mydomain.com` (without the ***www***), are not supported

<doc-alert type="info">
  Custom domains are available for Business and Enterprise customers.
</doc-alert>

### Create a custom domain

In the workspace domain section, open the dropdown menu "create domain" and click on **Create Custom domain** :

<illustration width="2442" height="871" src="docs/createCustomDomain-001.png" caption="Create a custom domain"></illustration>

<doc-alert type="warning"> Validation and generation of each CNAME can take several minutes.</doc-alert>

<doc-alert type="info">Using multiple environments? Check our [Multiple environments pattern](https://www.twicpics.com/docs/guides/multiple-environments).</doc-alert>

---

## Path Configuration

# Path Configuration

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

Upon creating your account, your very own TwicPics domain is available. All your image interactions will now be made through it, and you can attach as many image sources as you want using **our powerful path system**. This way, you can serve assets stored in multiple locations, such as CMS, DAM, cloud buckets, etc., all through a unique TwicPics domain.

To edit an existing path, click the _three dots icon_ at the right of the path description in the domain paths listing.

<illustration width="2430" height="946" src="docs/screenshoot-path-options.png" caption="Path options"></illustration>

## Basic Setup

Creating a path in TwicPics involves providing two key pieces of information for each path you wish to establish:

1. **Path Name:** A unique identifier for the path. This name is used to reference and retrieve your assets through TwicPics (i.e., `https://<twicpics-domain-name>/<path-name>`)
2. **Source URL:** The HTTP-accessible URL where your assets are stored. TwicPics will fetch and deliver assets from this source.

<doc-alert>You can create multiple paths to connect various storage locations to your TwicPics domain, ensuring flexible and efficient asset delivery.</doc-alert>

### Source Authentication

If your source URL is publicly accessible, no further configuration is required. However, if your source requires authentication, TwicPics supports several authentication methods to ensure secure access to your assets:

- **Basic HTTP Authentication:** Utilizes a username and password to provide access. Ensure your source supports this method and you have the necessary credentials.
- **Bearer Tokens:** Ideal for APIs or services that require a token for authentication. Provide the token generated by your service.
- **AWS Signature V4:** Compatible with S3 and all S3-compatible services (e.g., Google Cloud, Scaleway, Cloudflare). This method signs requests with your credentials for secure access.
- **Azure SAS:** For Azure storage, Shared Access Signatures (SAS) provide secure, fine-grained access control to your assets.
- **Akeneo PIM (on-demand):** Specialized for Akeneo PIM sources. Contact TwicPics support to set up this method.

<doc-alert type="info">As a convenience, TwicPics already sends a `X-TwicPics-Token` header that is unique to your domain.</doc-alert>

## Advanced Path Options

Options are listed here in alphabetical order.

### Canonical Link Header

For better SEO, it is recommended to have all variants of the same image reference a single master link.

TwicPics can generate the header with this "canonical link" for you automatically.

Two options are available:

- `TwicPics URL`: the canonical link points to your image through this path, ensuring eventual default manipulation and overlay are applied. Your Source URL is **protected**: search engines will reference your TwicPics URL.
- `Source URL`: the canonical link points to your Source URL. Default manipulation and overlay will **not** be applied. Your Source URL is made **public**: search engines will reference your Source URL.

### Default Manipulation

<doc-alert>We refer to a list of one or several transformations as **a manipulation**.</doc-alert>

For each path, you can set a default manipulation. This is especially handy in order to protect your assets from web crawlers and to avoid ever distributing the full-resolution master image.

Let us say that the root path (`/`) of `<sub>.twic.pics` has its default manipulation set to `max=1000`.

This default manipulation will be applied after any manipulation provided using the [TwicPics API](https://www.twicpics.com/docs/reference/transformations).

Let us see what we get with a few examples:

| API Call                                                           | Final manipulation                |
| ------------------------------------------------------------------ | --------------------------------- |
| `https://<sub>.twic.pics/image.jpg`                                | `max=1000`                        |
| `https://<sub>.twic.pics/image.jpg?twic=v1/cover=1:1`              | `cover=1:1/max=1000`              |
| `https://<sub>.twic.pics/image.jpg?twic=v1/resize=2000/quality=60` | `resize=2000/quality=60/max=1000` |

Please note that, in this example and no matter what, TwicPics will always deliver an image that is at most 1000 pixels wide.

You could also use the default manipulation to ensure a minimum image quality, no matter the network conditions of the end-user. For instance, `quality-min=50` would ensure no image with a quality lower than 50 would be delivered, even to users on 2G networks.

In truth, any [transformation](https://www.twicpics.com/docs/reference/transformations) can be used, and the possibilities are virtually endless.

Another neat trick is adding transformations before and/or after the ones provided through the API.

By placing the star symbol (`*`) in place of a transformation, you indicate where the manipulation provided through the API has to be placed.

Let us say, for instance, that you wish to provide a default quality of 50 while making it possible to override the value through the API. The correct manipulation for this would be `quality=50/*`.

Here is how it would behave in several examples:

| API Call                                                           | Final manipulation                  |
| ------------------------------------------------------------------ | ----------------------------------- |
| `https://<sub>.twic.pics/image.jpg`                                | `quality=50`                        |
| `https://<sub>.twic.pics/image.jpg?twic=v1/cover=1:1`              | `quality=50/cover=1:1`              |
| `https://<sub>.twic.pics/image.jpg?twic=v1/resize=2000/quality=60` | `quality=50/resize=2000/quality=60` |

Please note that while the first two resulting images will have a quality of 50, the third one will have a quality of 60 as specified through the API.

Of course, it is possible to create a default manipulation that will act before **and** after the one provided through the API.

For instance, we could combine a default quality with a maximum width by setting the default manipulation to `quality=50/*/max=1000`.

How will our previous examples behave in such an instance?

| API Call                                                           | Final manipulation                           |
| ------------------------------------------------------------------ | -------------------------------------------- |
| `https://<sub>.twic.pics/image.jpg`                                | `quality=50/max=1000`                        |
| `https://<sub>.twic.pics/image.jpg?twic=v1/cover=1:1`              | `quality=50/cover=1:1/max=1000`              |
| `https://<sub>.twic.pics/image.jpg?twic=v1/resize=2000/quality=60` | `quality=50/resize=2000/quality=60/max=1000` |

This is a resounding success! No matter what the manipulation provided through the API is, we do have a default, overridable quality of 50, and no image more than 1000 pixels wide will be delivered.

One final note: since [TwicPics Components](https://www.twicpics.com/docs/essentials/components) and [TwicPics Native](https://www.twicpics.com/docs/essentials/native) issue API requests under the hood, They will respect default manipulations too.

Let us assume we have the same default manipulation as in the previous example (`quality=50/*/max=1000`) and let us consider the following element

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

Let us also assume this element is styled so that its width ends up being 2000 pixels. The manipulation applied to `image:man.jpg` will be `resize=2000` but, since we have a default manipulation `quality=50/*/max=1000`, the actual final manipulation will be `quality=50/resize=2000/max=1000`. So the image quality will be 50 and its width 1000, as expected.

### Image Fallback URL

This fallback image will be used if and when a `4xx` status code (`400`, `404`, etc) is issued by your server.

Consider the following path configuration for `<sub>.twic.pics`:

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

and say you have set the fallback of `/` to `https://www.my-company.com/fallback.jpg`.

At one point, you end up requesting `https://<sub>.twic.pics/ilage.jpg` instead of `https://<sub>.twic.pics/image.jpg`. TwicPics will try and request `https://www.my-company.com/ilage.jpg`, get a `404` in return, and thus, switch to `https://www.my-company.com/fallback.jpg`.

Eventual transformations will be applied to the fallback as if it were the intended target. So `https://<sub>.twic.pics/ilage.jpg?twic=v1/resize=300` will return a 300 pixels wide version of `https://www.my-company.com/fallback.jpg`.

If, for whatever reason, requesting the fallback results in a `4xx` status code, then this status code will be propagated back to the requester.

If no fallback is provided, TwicPics will simply propagate the original `4xx` status code.

### Mask

The `mask` feature introduces an advanced capability for users to create complex image compositions through the use of mask layers. This feature allows for dynamic and creative control over the visibility of different parts of an image, enabling the creation of intricate visual effects and compositions.

#### What is a Mask Layer?

A mask layer is a tool used in digital image processing to determine which parts of an image should be visible or transparent. In essence, it's like a stencil over your image. The mask layer itself is an image (either a Scalable Vector Graphics (SVG) file or a bitmap image) where black and white indicate the visibility of the corresponding parts of the source image.

- White areas in the mask layer indicate 100% visibility. These areas of your image will be fully visible.
- Black areas represent 100% transparency. These parts of your source image will be completely transparent, creating openings in the image.

#### Using the Mask Feature

To use the `mask` feature, you'll need to provide the URL of an image that will serve as the mask layer. This can be either a SVG or a bitmap image. TwicPics will then apply this mask to all images or videos delivered through this path, following the rules of visibility and transparency defined by the mask's colors.

<illustration src="docs/mask-example.png" width="1920" height="664" caption="Masking demo"></illustration>

### Metadata

By default, TwicPics will filter out any metadata from your source asset to gain precious bytes.

However, if your images contain information you need or want to still be present in the transformed image (like a copyright notice for instance), you can switch the `Keep metadata` button on.

<doc-alert type="info">Note that EXIF orientation and color profiles may be changed or removed respectively since they are used for generating the transformed image.</doc-alert>

### Overlay

With the `overlay` feature, you can create a dynamic composition or add a watermark for all images or videos requested through the path.

You then have to provide the `URL` of the overlay image, and several options are available for:

- where the overlay is positioned in the images or videos: `Anchor`
- how the overlay is sized and if it is repeated: `Mode`
- how opaque the overlay has to be: `Opacity`
- How the overlay is scaled relative to the size determined by the given mode: `Scale`

Tweaking and testing overlaying can be a bit cumbersome: it can take several minutes for the configuration to be propagated to the TwicPics servers, and our CDN will retain any transformed image or video for at least thirty minutes and up to five days.

As such, we recommend you use an unused path (i.e., one not in production) to test overlaying. We also recommend relying on an incrementing URL parameter to ensure you do not hit the CDN cache.

Once you are satisfied with overlaying on your test path, simply apply the exact same configuration to your production path.

#### Anchor

The `Anchor` option determines where the overlay is positioned in the image or video.

Available values are:
`center`, `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right`

#### Mode

`Mode` determines how the overlay should be resized and/or repeated relative to the image or video. All modes take the `Anchor` into account for initial positioning.

Available modes are:

| Mode    | Description                                                    |
| ------- | -------------------------------------------------------------- |
| stretch | The overlay is sized to fill the image. The overlay will completely fill the image. If the overlay's aspect ratio does not match the aspect ratio of its box, then the overlay will be stretched to fit. |
| contain | The overlay is scaled to maintain its aspect ratio while fitting within the image. The overlay is made to fill the box, while preserving its aspect ratio, so the object will be "letterboxed" if its aspect ratio does not match the aspect ratio of the box. |
| cover   | The overlay is sized to maintain its aspect ratio while filling the image. If the overlay's aspect ratio does not match the aspect ratio of the image, then the overlay will be clipped to fit. |
| fill    | The overlay is fully contained in the image and repeated if needed. |

#### Opacity

`Opacity` determines how opaque the overlay should be. It is a number between `0` (invisible) and `1` (fully opaque).

#### Scale

`Scale` is a number specifying a scale factor to make the overlay scale by the same factor along both the X and Y axes. This scale factor is relative to the size determined by the given mode. For example, an half the image size overlay is produced using a `scale` factor of `0.5` with the `contain` mode.

#### URL

`URL` specifies the location of the overlay image.

TwicPics will accept the usual, non-animated, formats: [AVIF](<https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)>), [GIF](https://en.wikipedia.org/wiki/GIF), [HEIF](https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format), [JPEG](https://en.wikipedia.org/wiki/JPEG), [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics), and [WebP](https://en.wikipedia.org/wiki/WebP) with the notable addition of [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics).

In case of an overlay with no transparency, be sure to use `Opacity` unless you want the original image or video to disappear and be replaced with the overlay itself!

#### Examples

In the following examples, we use the `Overlay` feature to process watermarked images. In this case, the overlay is an SVG file.

| Setup | Result |
| ----- | ------ |
| `anchor=center`<br>`mode=stretch`<br>`opacity=1`<br>`scale=1` | ![](https://assets.twic.pics/docs/watermark-center-strech-1-1.jpg) |
| `anchor=center`<br>`mode=contain`<br>`opacity=1`<br>`scale=1` | ![](https://assets.twic.pics/docs/watermark-center-contain-1-1.jpg) |
| `anchor=center`<br>`mode=cover`<br>`opacity=1`<br>`scale=1` | ![](https://assets.twic.pics/docs/watermark-center-cover-1-1.jpg) |
| `anchor=center`<br>`mode=fill`<br>`opacity=1`<br>`scale=1` | ![](https://assets.twic.pics/docs/watermark-center-fill-1-1.jpg) |
| `anchor=center`<br>`mode=contain`<br>`opacity=1`<br>`scale=0.33` | ![](https://assets.twic.pics/docs/watermark-center-contain-1-033.jpg) |
| `anchor=center`<br>`mode=contain`<br>`opacity=0.5`<br>`scale=0.5` | ![](https://assets.twic.pics/docs/watermark-center-contain-05-05.jpg) |
| `anchor=bottom-right`<br>`mode=contain`<br>`opacity=1`<br>`scale=0.33` | ![](https://assets.twic.pics/docs/watermark-bottom-right-contain-1-033.jpg) |

<doc-alert type="warning">In the case of SVG files, be aware no dynamic nor remote operation will be supported, meaning no animation and no linked content. All styles should be inlined in the file, and raster images should be embedded as base64-encoded data URLs.</doc-alert>

### Passthrough

By default, TwicPics will deliver images and videos. In the case where an unsupported media type (`PDFs`, `CSS files`, `JavaScript`, etc) is encountered, a standard `HTTP 415` error response will be returned.

You can change this paradigm by switching the `Passthrough` button on. TwicPics will then act as a standard content delivery network (CDN) and deliver, in addition to optimized images and videos, any type of unsupported asset **without applying them any transformation**.

#### Passthrough Use Cases

Passthrough is particularly useful if you need to utilize TwicPics paths to deliver assets other than images and videos. It ensures seamless delivery of diverse media types through the TwicPics CDN.

#### Passthrough Best Practices

Passthrough should be used judiciously. It is intended as a solution for scenarios where there is no alternative to using TwicPics paths for asset delivery. You are encouraged to evaluate your needs and activate Passthrough only when necessary to optimize cost and performance.

<doc-alert type="info">Please note that all traffic related to the delivery of assets via the Passthrough feature will be invoiced accordingly. This includes the data associated with non-image and non-video files.</doc-alert>

### Referrer filter

The Referrer Filter feature enhances security and control over who can access your assets. By specifying a list of domains, you can restrict incoming requests based on the Referer header, ensuring that only authorized sources are able to retrieve content.

#### How Referrer filter works?

When a request is made, TwicPics examines the Referer header. If the domain making the request matches one of the user-defined domains in the filter list, the request is allowed. If not, a 403 Forbidden response is issued, blocking access to the resource.

#### Configuring Your Referrer Filter

To use the Referrer Filter, provide a list of domains you wish to allow. There are three ways to specify domains:

- **Root (Apex) Domain:** Specify the root domain to accept requests only from the root domain itself. For example, **`domain.com`** will permit requests from domain.com but not from any subdomains like **`www.domain.com`**.
- **Specific Subdomain:** Specify a full subdomain to restrict access to that particular subdomain. For instance, **`www.domain.com`** will allow requests from **`www.domain.com`** only, excluding any other subdomains or the root domain.
- **Wildcard Subdomains:** Use **`*`** to denote wildcard subdomains, allowing requests from any subdomain of the specified domain. For example, **`*.domain.com`** will enable requests from **`www.domain.com`**, **`images.domain.com`**, and any other subdomains.

#### Handling Unauthorized Access

If a request does not meet the criteria specified in your Referrer Filter, TwicPics will return a 403 Forbidden response. This ensures that only requests from authorized domains can access your resources.

#### Referrer Filter Best Practices

- **Review your domain list regularly** to ensure it reflects your current access control needs.
- **Be specific** in your domain choices to minimize the risk of unauthorized access.
- **Test your configuration** thoroughly to prevent accidental blocks or exposure.

<doc-alert type="warning">Ensure that the specified filters align with your security and access control requirements. Misconfigurations can lead to unintended access restrictions, impacting the availability of your resources to legitimate users.</doc-alert>

### Source Request Headers

For each path, you can set a list of headers to be sent to your server.

This is especially handy in order to set up any custom header that would be checked by your server.

### Upscale

This feature allows for the upscaling of images and videos to meet the demanding requirements of various platforms and devices, ensuring your content always fits. Once enabled, it permits TwicPics to upscale your source assets to a higher resolution upon request.

#### How upscaling works?

By default (Upscale turned off), TwicPics will prevent upscaling and limit renditions to the maximum size of the source asset.

When the Upscale feature is active, and a request is made for a rendition larger than the source asset's original dimensions, TwicPics will upscale the asset to match the requested size. For instance, if your source image or video is 1000 pixels in width and you request a rendition of 2000 pixels, TwicPics will deliver an upscaled version at 2000 pixels.

<doc-alert type="warning">
<strong>Quality Considerations</strong> — It's important to note that while the Upscale feature increases the dimensions of your assets, it does not enhance the intrinsic quality of the images or videos. The upscaling process aims to maintain the original quality as much as possible at a higher resolution but does not add additional detail that was not present in the original source.
</doc-alert>

## Catch-All Path Segments

Using the character `*`, you can specify a "catch-all" path segment. What it means is that this section of your TwicPics URL can be anything as long as it does not contain a slash (`/`).

Using this technique, you can insert meaningful, arbitrary slugs in your TwicPics URL and boost SEO.

For instance, the configuration below:

| path | source images folder                |
| ---- | ----------------------------------- |
| `/*` | `https://media.my-company.com/web/` |

will enable the mappings below:

| TwicPics URL                                  | source image URL                         |
| --------------------------------------------- | ---------------------------------------- |
| `https://<sub>.twic.pics/pair-of-shoes/1.png` | `https://media.my-company.com/web/1.png` |
| `https://<sub>.twic.pics/smart-phone/2.png`   | `https://media.my-company.com/web/2.png` |

Catch-all path segments can appear anywhere in your path and as many times as necessary.

For instance, the configuration below:

| path       | source images folder                |
| ---------- | ----------------------------------- |
| `/sales/*` | `https://media.my-company.com/web/` |

will enable the mappings below:

| TwicPics URL                                   | source image URL                         |
| ---------------------------------------------- | ---------------------------------------- |
| `https://<sub>.twic.pics/sales/i-phone/1.png`  | `https://media.my-company.com/web/1.png` |
| `https://<sub>.twic.pics/sales/nike-air/2.png` | `https://media.my-company.com/web/2.png` |

When given a choice between a catch-all segment or a more specific one, TwicPics will always favor the most specific one, regardless of the order in which the paths have been created.

For instance, the configuration below:

| path        | source images folder                 |
| ----------- | ------------------------------------ |
| `/*`        | `https://media.my-company.com/web/`  |
| `/specific` | `https://www.my-company.com/assets/` |

will enable the mappings below:

| TwicPics URL                               | source image URL                          |
| ------------------------------------------ | ----------------------------------------- |
| `https://<sub>.twic.pics/unspecific/1.png` | `https://media.my-company.com/web/1.png`  |
| `https://<sub>.twic.pics/specific/2.png`   | `https://www.my-company.com/assets/2.png` |

Beware that a catch-all segment will take priority over a path finishing at the same level.

For instance, the configuration below:

| path    | source images folder                 |
| ------- | ------------------------------------ |
| `/s1/*` | `https://media.my-company.com/web/`  |
| `/s1`   | `https://www.my-company.com/assets/` |

will enable the mappings below:

| TwicPics URL                          | source image URL                          |
| ------------------------------------- | ----------------------------------------- |
| `https://<sub>.twic.pics/s1/1.png`    | `https://www.my-company.com/assets/1.png` |
| `https://<sub>.twic.pics/s1/s2/2.png` | `https://media.my-company.com/web/2.png`  |

## Multiple Sources Paths

Multiple Sources Paths allow you to transform media from any storage through a single, unified path.

Unlike regular paths, Multiple Sources Paths do not reference a Source URL but rather expect the URL of the source image to be provided at the API level.

As such, and to ensure external users cannot use TwicPics on your behalf, these URLs must be encrypted.

<doc-alert type="warning">
Multiple Sources Paths should be used as a last resort. Carefully consider the tradeoffs between maintaining as many paths as needed and managing the encryption of URLs.
</doc-alert>

### How It Works

When creating a Multiple Sources Path, you'll be provided with an **Encryption Key**.

<doc-alert type="warning">
The Encryption Key will only be shown **once**, after creating the path. Make sure to store in safely.
</doc-alert>

Let's take the following example:

- A Multiple Sources Path named `multi` on your `company.twic.pics` domain
- An image found at `https://example.com/image.png`.

Using the [Encryption Algorithm](#encryption-algorithm) described below, you will have to encode `https://example.com/image.png` into something akin to `aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n`.

The image will be accessible through `https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n` and can be referenced in the `src` prop (or `data-twic-src` attribute if not using components) as `image:multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n`.

You can now apply [transformations](https://www.twicpics.com/docs/reference/transformations) to the image as you would on a regular path:

- `https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n?twic=v1/cover=500x500`
- `https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n?twic=v1/output=preview`

### Encryption Algorithm

TwicPics expects the URLs to be encrypted as follows:

- The input URL is reversed (i.e. `https://domain/path` becomes `htap/niamod//:sptth` )
- The reversed URL is encrypted using the Advanced Encryption Standard Algorithm with a 128-bit key
- The resulting encrypted string is encoded in Base64
- Finally, all forward slashes are replaced by dashes in the resulting encoded string

The example below implements the encryption algorithm:

<code-sample :languages="snippets.encryption"></code-sample>

## Paths Resolution

### Using Absolute URLs

Paths can have any format and as such, they can look like absolute URLs.

For instance, the following configuration:

| path                          | source images folder          |
| ----------------------------- | ----------------------------- |
| `/https://www.my-company.com` | `https://www.my-company.com/` |

would make it so `https://<sub>.twic.pics/https://www.my-company.com/assets/image.png` points to `https://www.my-company.com/assets/image.png`.

Nothing impressive so far but it can come in handy when combined with the [TwicPics Native](https://www.twicpics.com/docs/essentials/native).

Since the TwicPics understands relative URLs in both [`data-twic-src`](https://www.twicpics.com/docs/reference/native-attributes#data-twic-src), [`data-twic-poster`](https://www.twicpics.com/docs/reference/native-attributes#data-twic-poster) and [`data-twic-background`](https://www.twicpics.com/docs/reference/native-attributes#data-twic-background) attributes, you can seamlessly handle assets located on the same server as your webpages.

Let's say `https://www.my-company.com/my-page.html` contains the following `img` element:

```html
<img data-twic-src="assets/image.png" />
```

This will be rightfully understood as `https://www.my-company.com/assets/image.png` and the image will be optimized by TwicPics automagically.

### Conflicting Paths

Paths do not have to be on the same hierarchical level. For instance, the following configuration:

| Domain path | Source URL                      |
| ----------- | ------------------------------- |
| `/`         | `https://www.my-company.com/`   |
| `/media`    | `https://media.my-company.com/` |

would make it so:

- `https://<sub>.twic.pics/media/logo.png` points to `https://media.my-company.com/logo.png`
- `https://<sub>.twic.pics/banner.png` points to `https://www.my-company.com/banner.png`

Doing so will make it impossible to access any image inside `https://www.my-company.com/media/`.

---

## TwicPics Components

# TwicPics Components

<illustration src="github/components/main/documentation/resources/components-cover.png" width="2400" height="1256" alt="TwicPics Components"></illustration>

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

## What is TwicPics Components?

**TwicPics Components** is a **collection of web components** that make it dead easy to unleash the power of TwicPics in your projects.

Whether you need to display a content image, showcase a short video, or ensure optimal performance with _Large Contentful Paint_ (LCP) care, TwicPics Components has you covered.

### Display a Critical Image

If you need to display **critical images** with _art direction_ support, you can use the `<TwicPicture>` component.

It is a drop-in replacement for the standard `picture` tag and is based directly on the [TwicPics API](https://www.twicpics.com/docs/essentials/api) without additional effort.

```html
<!-- Before -->
<picture>
  <source
    media="(min-width: 1280px)"
    srcset="wide-image.jpg, wide-image-2x.jpg 2x, wide-image-3x.jpg 3x"
  >
  <source
    media="(min-width: 768px)"
    srcset="squared-image.jpg, squared-image-2x.jpg 2x, squared-image-3x.jpg 3x"
  >
  <img
    srcset="portrait-image.jpg, portrait-image-2x.jpg 2x, portrait-image-3x.jpg 3x"
    src="portrait-image.jpg"
  >
</picture>

<!-- After -->
<TwicPicture
  src="your-master-image.jpg"
  ratio="3/4, @md 1, @xl 16/9"
/>
```

### Display a Content Image

Suppose you want to display a **pixel-perfect image** with optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box. In that case, you can use the `<TwicImg>` component.

It's a drop-in replacement for the standard `img` tag.

```html
<!-- Before -->
<img src="https://example.com/your-image.jpg" />

<!-- After -->
<TwicImg src="your-image.jpg" />
```

### Display a Video

For seamless playback of [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), use the `<TwicVideo>` component. It's a sibling of `<TwicImg>` and serves as a drop-in replacement for the standard `video` tag.

```html
<!-- Before -->
<video >
  <source src="https://example.com/your-video.mp4" type="video/mp4">
  <!-- ... other video sources ... -->
</video>

<!-- After -->
<TwicVideo src="your-video.mp4" />
```

## Supported frameworks

Jump to the docs:

- [Angular](https://www.twicpics.com/docs/components/angular)
- [Flutter](https://www.twicpics.com/docs/components/flutter)
- [React](https://www.twicpics.com/docs/components/react), [React Native](https://www.twicpics.com/docs/components/react-native), [Gatsby](https://www.twicpics.com/docs/components/gatsby), and [Next.js](https://www.twicpics.com/docs/components/next)
- [Svelte 3](https://www.twicpics.com/docs/components/svelte-3), [Svelte 4](https://www.twicpics.com/docs/components/svelte-4), [Svelte 5](https://www.twicpics.com/docs/components/svelte-5) and [SvelteKit](https://www.twicpics.com/docs/components/sveltekit)
- [Vue 2](https://www.twicpics.com/docs/components/vue-2) & [Vue 3](https://www.twicpics.com/docs/components/vue-3), and [Nuxt 2](https://www.twicpics.com/docs/components/nuxt-2) & [Nuxt 3](https://www.twicpics.com/docs/components/nuxt-3)
- [Web Components](https://www.twicpics.com/docs/components/webcomponents)

## Live demos

Regardless of the framework you work with, TwicPics is the most efficient solution to deliver your images and your videos and make them as responsive as desired.

Explore our demos and integration examples for :

- [Angular](https://twicpics-angular-demo.netlify.app/)
- [React](https://twicpics-react-demo.netlify.app/), [Next.js](https://twicpics-next-demo.netlify.app/) and [Gatsby.js](https://twicpics-gatsby-demo.netlify.app/)
- [Vue.js (version 2)](https://twicpics-vue2-demo.netlify.app/), [Vue.js (version 3)](https://twicpics-vue3-demo.netlify.app/), [Nuxt.js (version 2)](https://twicpics-nuxt2-demo.netlify.app/) and [Nuxt.js (version 3)](https://twicpics-nuxt3-demo.netlify.app/)
- [Svelte (version 3)](https://twicpics-svelte3-demo.netlify.app/), [Svelte (version 4)](https://twicpics-svelte4-demo.netlify.app/), [Svelte (version 5)](https://twicpics-svelte5-demo.netlify.app/) and [SvelteKit](https://twicpics-sveltekit-demo.netlify.app/)

## Feedback and support

TwicPics Components are open-source. Feel free to [open an issue](https://github.com/TwicPics/components/issues) on GitHub for feature requests and bugs.

---

## TwicPics Native

# 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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/docs/essentials/native#lazy-loading) should be marked with `data-batman-view` rather than `data-twic-view`
- [lifecycle](https://www.twicpics.com/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`](https://www.twicpics.com/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)

---

## TwicPics API

# TwicPics API

TwicPics is powered by a **URL-based API** that can transform and manipulate your visual assets.

When using [TwicPics Components](https://www.twicpics.com/docs/essentials/components) or [TwicPics Native](https://www.twicpics.com/docs/essentials/native), the API request is generated using your browser context. But in some cases, you might want to write the API requests yourself.

TwicPics API offers a broad array of [transformations](https://www.twicpics.com/docs/reference/transformations#list-of-transformations) to manipulate your media in any way you desire.

There are two kinds of transformations: ones that actually modify the image (or video) and others that change the context of further transformations down the manipulation chain.

## Syntax

All transformations follow the same structure: `<name>=<parameters>`

where:

- `<name>` is the name of the transformation
- `<parameters>` is an expression specifying the parameters for the transformation

For instance:

- `resize=400` will resize the image to 400 pixels in width while conserving the source image aspect ratio
- `resize=640x480` will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio

## Fundamentals

<doc-alert>We refer to a list of one or several transformations as **a manipulation**.</doc-alert>

Transformations can be chained together using the character `/`. There is no limit to the number of transformations you can chain, save for the limit in size of a URL as enforced by your browser. No matter how complex the manipulation, TwicPics will optimize it for speed and accuracy on the fly.

### Focus point

Transformations behave differently depending on which point in the image is the main focus. TwicPics will do its best to keep this _focus point_ as central as possible within the transformed image.

By default, the _focus point_ is in the middle of the image, but you can change its coordinates using the [focus](https://www.twicpics.com/docs/reference/transformations#focus) transformation.

### Chaining transformations

When adding a transformation to the chain, the parameters given are interpreted as if previous transformations had already been performed (ie. as if the source image was the result of the previous transformations).

For instance:

- `resize=340/resize=50p` will result in an image that is 170 pixel-wide
- `resize=50p/focus=20x10` will put the _focus point_ at coordinates `40x20` of the source image

Since TwicPics will optimize the manipulation, be aware that a transformation may shadow what came before it. For instance, `resize=50p/resize=340` will result in an image that is 340 pixel-wide: TwicPics will simply ignore the first _resize_.

## URL format

To perform an API call to TwicPics, you need to provide:

- the image or video to manipulate
- the [list of transformations](https://www.twicpics.com/docs/reference/transformations#fundamentals) to be applied

The URL for an API request has the following format:

```curl
https://<your-twicpics-domain>/<path_to_image>?twic=v1/<manipulation>
```

Where:

- `https://<your-twicpics-domain>/<path_to_image>` is the image path
- `?twic=v1/<manipulation>` is a list of one or more [transformations](https://www.twicpics.com/docs/reference/transformations#list-of-transformations)

<doc-alert>
Transformations are always applied in order. See <a href="/docs/reference/transformations#chaining-transformations">Chaining transformations</a>.
</doc-alert>

For instance, `https://<your-twicpics-domain>/myImage.png?twic=v1/resize=450` will resize `http://mydomain.com/myimage.png` to a width of 450 pixels while preserving its aspect ratio.

If you wish to pass query parameters to the server delivering the source image, just add it to the query string before or after the manipulation using the usual query string separator `&`.

Going back to the previous example, you could use one of these two options:

```curl
https://<your-twicpics-domain>/myImage.png?twic=v1/resize=450&param=value
https://<your-twicpics-domain>/myImage.png?param=value&twic=v1/resize=450
```

---


---

# Basics

## Supported formats

# Supported formats

## Images

TwicPics only recognizes `AVIF`, `GIF`, `HEIF`, `JPEG`, `PNG`, and `WebP` files as transformable images. In the case of unsupported file formats, the default behavior is to return an `HTTP 415` error.

<doc-alert>Ideally though, we recommend using original high-quality `JPEG` images. Your optimized images will benefit from the best ratio between quality and weight.</doc-alert>

<!-- TODO: move this part to "image best practices" -->
<!-- <doc-alert type="warning">For performance reasons, we do not recommend the use of the `AVIF` format for your optimized assets.</doc-alert>

En effet, bien que le format AVIF soit plus léger, il engendre :

- une consommation importante de ressources à la décompression.
- un premier appel plus couteux en terme de performances, lié à son temps d'encodage plus long.

Cela a pour effet de consommer de façon excessive la batterie des terminaux de vos utilisateurs sur mobile et de ralentir l'affichage de vos pages. Ce que le format AVIF apporte en terme de poids est donc perdu sur ces deux aspects. -->

## Videos

TwicPics accepts all formats of your original videos.

<doc-alert>We recommend that you use the `MP4` format for your original videos. Encoding performance will be better.</doc-alert>

## Other file types

By default, TwicPics only handles images and videos.

However, by activating the **passthrough feature**, you can allow unsupported files to pass through unaltered. This means you can use your TwicPics domain to deliver CSS or JavaScript files and take advantage of the TwicPics CDN. There is obviously a limit to the size of such files, but it is plenty enough for web usage.

---

## Limits and restrictions

# Limits and restrictions

## Original media

TwicPics imposes limits on your original media to avoid specific problems related to their recovery – e.g., slowness or overload, time-out, etc.

### Images

- Max pixels: `36 million`
- Max weight: `20Mb`

<!-- TODO: create a dedicated page in the future "image best practices" section
* NOTION – https://www.notion.so/twicpics/Recommandations-images-masters-5b87f70d93444193a26d8a59ee37b29b?pvs=4
* Help center – https://help.twicpics.com/en/articles/6550163-any-image-recommendations

<doc-alert>[See recommendations](/) on normalizing your original images.</doc-alert>
-->

### Videos

- Max duration: `30 seconds`
- Max FPS: `30 FPS`
- Max pixels: `36 million`
- Max weight: `36Mb`

<doc-alert>When a media to optimize exceeds at least one of these limits, the TwicPics API will return a `502` error.</doc-alert>

---

## Errors handling

# Errors handling

Whenever something goes wrong, TwicPics will issue an HTTP error with a sensible [status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) and a short explanation in plain text as a body.

TwicPics will error when:

- There is a syntax error in the manipulation expression
- The authentication identifier is invalid
- The URL of the source asset is not well-formed, or its protocol is not supported
- The domain of the source asset is not registered (see the documentation about domain name registration)
- The source asset is unreachable (i.e., the `GET` request to retrieve it resulted in an HTTP error)
- The source asset is of an unsupported format (only [AVIF](<https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)>), [GIF](https://en.wikipedia.org/wiki/GIF), [HEIF](https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format), [JPEG](https://en.wikipedia.org/wiki/JPEG), [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics), and [WebP](https://en.wikipedia.org/wiki/WebP), and most `video` files are currently supported)
- The source asset, the output asset, or any intermediate asset created while processing the transformations doesn't respect the internal pixel and/or byte size limits of TwicPics (i.e., one of the assets has a dimension of zero or is "too big")
- A transformation ends up cropping outside of the asset (for instance, when attempting to crop 500 pixels out of an asset that is only 200 pixels wide)

<doc-alert type="info">Whenever an asset does not show on your web page, check the network tab of your favorite dev tool for those red-colored lines indicative of a network error.</doc-alert>

---


---

# Reference

## TwicPics Native Attributes

# TwicPics Native Attributes

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

TwicPics Native provides three types of attributes :

- **medium attributes** which specify a source, a poster or a background medium
- **modifier attributes** that change how those media are transformed
- **medium-specific modifier attributes** which are modifier attributes that only apply to a specific medium (source, poster or background)

## Medium Attributes

### data-twic-src

_Default value_: `""` _(empty)_

Specifies the path of the source image or video.

```html
<img data-twic-src="image:<path_to_image>" />

<video data-twic-src="image:<path_to_video>"></video>
```

For `img` elements, the attribute also accepts [placeholder expressions](https://www.twicpics.com/docs/reference/placeholders).

```html
<img data-twic-src="placeholder:auto" />
```

Using a placeholder expression makes it very easy to spy on the actual dimensions of your image whenever you're in doubt.

### data-twic-poster

_Default value_: `""` _(empty)_

Specifies the path of the source poster.

```html
<video data-twic-poster="image:<path_to_image>"></video>
```

The attribute also accepts [placeholder expressions](https://www.twicpics.com/docs/reference/placeholders).

```html
<video data-twic-poster="placeholder:auto"></video>
```

Using a placeholder expression makes it very easy to spy on the actual dimensions of your video whenever you're in doubt.

### data-twic-background

_Default value_: `"none"`

Specifies the urls of the background images.

```html
<!-- single background -->
<img data-twic-background="url(image:<path_to_image>)" />

<!-- multiple backgrounds -->
<img
  data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_1>)"
/>
```

Twipics Native will only recognize and handle urls in the form of `url(<value>)` where `<value>` is a non-quoted, single-quoted, or double-quoted url. As such, it allows mixing automatically handled background images with non-image backgrounds, like so:

```html
<div
  data-twic-background="linear-gradient(rgba(0, 0, 255, 0.5)), url(image:banner.jpeg)"
></div>
```

Also note that the value of a url can be a [placeholder expression](https://www.twicpics.com/docs/reference/placeholders).

```html
<!-- single background -->
<img data-twic-background="url(placeholder:auto)" />
```

Using a placeholder expression makes it very easy to spy on the actual dimensions of your background image whenever you're in doubt.

## Modifier Attributes

<doc-alert type="info">You'll seldom need to use modifier attributes (with the notable exception of [`data-twic-bot`](#data-twic-bot) and [`data-twic-intrinsic`](#data-twic-intrinsic)). Styling elements with CSS will suffice most of time, especially given TwicPics Native does understand `background-size` and `object-fit` directives and will generate API calls appropriately.</doc-alert>

### data-twic-bot

_Default value_: `""` _(empty)_

Specifies the manipulation to be applied to the medium when search engine bots are visiting. The attribute will override the value of [`data-twic-transform`](#data-twic-transform) when search engine bots are crawling your page and it supports the exact same syntax.

<doc-alert type="info">
When used with an empty value, the <nuxt-link to="/docs/essentials/path-configuration#default-manipulation">default transformations</nuxt-link> will be applied.
</doc-alert>

Search engines detected include, amongst others:

- [Google](https://www.google.com)
- [Bing](https://www.bing.com)
- [Yahoo](https://search.yahoo.com)
- [DuckDuckGo](https://duckduckgo.com)
- [Baidu](https://www.baidu.com)
- [Yandex](https://yandex.com)
- [Sogou](https://www.sogou.com)
- [Exalead](https://www.exalead.com)

If absent, [`data-twic-transform`](#data-twic-transform) will be used indiscriminately for all visitors, including search engine bots. This can be a problem for SEO when bots emulate different devices and TwicPics Native generates separate variants accordingly.

```html
<img data-twic-src="image:<path_to_image>" data-twic-bot="cover=400x400" />

<video data-twic-poster="image:<path_to_image>" data-twic-bot="cover=400x400">
  <div
    data-twic-background="url(image:<path_to_image>)"
    data-twic-bot="cover=400x400"
  ></div>

  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-bot="cover=400x400"
  ></div>
</video>
```

In the example above, while regular visitors will receive different variants depending on their browsing context, search engine bots will always get a 400 pixels wide, 400 pixels high version of your image. Search engines will have a single point of reference which is a known boost to SEO.

<doc-alert type="info">Note that [`data-twic-focus`](#data-twic-focus) and [`data-twic-step`](#data-twic-step) will still be used for when search engine bots are visiting.</doc-alert>

### data-twic-eager

_Default value_: `<n/a>`

When the `data-twic-eager` attribute is present, the element will be handled by TwicPics Native as soon as possible regardless of if said element is visible or not. Though using `data-twic-eager` is not recommended as a general practice, it can prove useful in ensuring specific media are loaded ahead of the corresponding elements entering the viewport.

```html
<!-- Default lazy loading behavior -->
<img data-twic-src="image:<path_to_image>" />

<!-- Loading the image as soon as possible -->
<img data-twic-src="image:<path_to_image>" data-twic-eager />
```

### data-twic-focus

_Default value_: `none`

Specifies the [focus point](https://www.twicpics.com/docs/reference/transformations#focus-point) for transformations. The value of this attribute must be `none` or, like in [the focus API](https://www.twicpics.com/docs/reference/transformations#focus), valid [coordinates](https://www.twicpics.com/docs/reference/parameters#coordinates), an [anchor](https://www.twicpics.com/docs/reference/parameters#anchor) or `auto`.

```html
<img data-twic-src="image:<path_to_image>" data-twic-focus="auto" />

<img data-twic-src="image:<path_to_image>" data-twic-focus="top-left" />

<video data-twic-poster="image:<path_to_image>" data-twic-focus="50px25p">
  <div
    data-twic-background="url(image:<path_to_image>)"
    data-twic-focus="152x467"
  ></div>

  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-focus="50px25p, none"
  ></div>
</video>
```

<doc-alert type="info">Note that, for multiple backgrounds, it is possible to specify multiple focuses.</doc-alert>

<doc-alert type="warning">Videos do not support focus `focus="auto"` yet.</doc-alert>

### data-twic-intrinsic

_Default value_: `none`

Specifies the intrinsic dimensions of the image. It's a _pixel [size](https://www.twicpics.com/docs/reference/parameters#size)_ that will allow TwicPics Native to make smarter decisions when generating the CSS-based image transformation:

1. it will prevent any form of upscaling
2. it will limit the number of variants generated (especially when combined with a high-enough [`data-twic-step`](#data-twic-step))

```html
<img
  data-twic-src="image:<path_to_image>"
  data-twic-intrinsic="<width>x<height>"
/>
```

Be careful when using `data-twic-intrinsic` in combination with `data-twic-transform`. The intrinsic dimension is to be determined after any transformation taking place **before** the CSS-based transformation (the transformation automatically generated by TwicPics Native based on your CSS definitions and referenced as `*` in `data-twic-transform`). Furthermore, `data-twic-intrinsic` is not considered at all if and when `data-twic-transform` does not trigger the CSS-based transformation (i.e has no reference to `*`).

Say your image intrinsic dimensions are `1000x1500`, here are the correct values of `data-twic-intrinsic` for some potential values of `data-twic-transform`:

| `data-twic-transform` | `data-twic-intrinsic`    |
| --------------------- | ------------------------ |
| _none_ or `*`         | `1000x1500`              |
| `crop=50p/*`          | `500x1500`               |
| `*/resize=50p`        | `1000x1500`              |
| `cover=500x500`       | _not taken into account_ |

<doc-alert type="info">`data-twic-intrinsic` is especially handy for hero images and hero videos: these full width and/or full height elements tend to generate a lot of variants if left unchecked which can seriously hinder cross-device caching.</doc-alert>

### data-twic-step

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

Enables overriding the default stepping value as specified by the global [`step`](https://www.twicpics.com/docs/essentials/native#step) parameter. Of course, if no value is provided, the default is used.

Stepping will round the computed width of the media to the closest multiple of `data-twic-step` while also changing the height in order to respect the original aspect ratio as closely as possible.

Overriding the default may be useful to ensure pixel-perfect resizing or to limit the number of potential variants generated on different devices for this specific element (see the [`step parameter documentation`](https://www.twicpics.com/docs/essentials/native#step) for more details).

<doc-alert>Note that to maximize cache effiencicy, the default step for <nuxt-link to="/docs/guides/video-optimization">videos</nuxt-link> is set to 100. Any values below will be ignored.</doc-alert>

```html
<!-- Pixel pefect -->
<img data-twic-src="image:<path_to_image>" data-twic-step="1" />

<!-- A lot less variants -->
<video data-twic-poster="image:<path_to_image>" data-twic-step="1000">
  <!-- Both on multiple backgrounds -->
  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-step="1, 1000"
  ></div>
</video>
```

<doc-alert type="info">Note that, for multiple backgrounds, it is possible to specify multiple steps.</doc-alert>

### data-twic-transform

_Default value_: `*`

Specifies the manipulation (ie. list of transformations) to be applied to the medium. The attribute accepts the full [transformations API](https://www.twicpics.com/docs/reference/transformations).

```html
<img
  data-twic-src="image:<path_to_image>"
  data-twic-transform="cover=1:1/resize=200"
/>

<video
  data-twic-poster="image:<path_to_image>"
  data-twic-transform="cover=400x300"
>
  <div
    data-twic-background="url(image:<path_to_image>)"
    data-twic-transform="resize=600x400"
  ></div>

  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-transform="cover=1:1/resize=200, contain=300x300"
  ></div>
</video>
```

<doc-alert type="info">Note that, for multiple backgrounds, it is possible to specify multiple transforms.</doc-alert>

As an addition, TwicPics Native provides two values, `W` and `H`, that represent the width and height of the content box of the current element respectively. Those aliases can be used wherever the manipulation syntax accepts a number.

```html
<img data-twic-src="image:<path_to_image>" data-twic-transform="cover=WxH" />

<video
  data-twic-poster="image:<path_to_image>"
  data-twic-transform="cover=(W/3)x(H/3)"
>
  <div
    data-twic-background="url(image:<path_to_image>)"
    data-twic-transform="contain=WxH"
  ></div>

  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-transform="cover=WxH, contain=(W/3)x(H/3)"
  ></div>
</video>
```

<doc-alert type="info">Please note those values are rounded by default (see [`data-twic-step`](#data-twic-step)).</doc-alert>

As a convenience, TwicPics Native adds shortcut transformations `contain`, `contain-max`, `contain-min`, `cover`, `cover-max`, `cover-min`, `max`, `min`, `resize`, `resize-max` and `resize-min` which are equivalent to `contain=WxH`, `contain-max=WxH`, `contain-min=WxH`, `cover=WxH`, `cover-max=WxH`, `cover-min=WxH`, `max=WxH`, `min=WxH`, `resize=WxH`, `resize-max=WxH` and `resize-min=WxH` respectively.

```html
<img data-twic-src="image:<path_to_image>" data-twic-transform="contain" />

<video data-twic-poster="image:<path_to_image>" data-twic-transform="cover">
  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-transform="cover, contain"
  ></div>
</video>
```

TwicPics Native also provides an additional transformation which is used by default: `*`. This is a CSS-based transformation that depends on the value of the `object-fit` or `background-size` CSS property of the element. For instance, when `object-fit` is `cover`, the `*` transformation is equivalent to `cover=WxH`.

The `*` transformation can be used into the `data-twic-transform` attribute as part of a more elaborate manipulation:

```html
<!-- Downsampling -->
<img data-twic-src="image:<path_to_image>" data-twic-transform="*/resize=25p" />

<!-- Precrop -->
<video
  data-twic-src="image:<path_to_image>"
  data-twic-transform="crop=50px50p/*"
>
  <!-- Both on two backgrounds -->
  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-transform="*/resize=25p, crop=50px50p/*"
  ></div>
</video>
```

Finally, if you don't want any transformation to occur, simple use `none`:

```html
<!-- Downsampling -->
<img data-twic-src="image:<path_to_image>" data-twic-transform="none" />

<!-- Precrop -->
<video data-twic-src="image:<path_to_image>" data-twic-transform="none">
  <!-- Both on two backgrounds -->
  <div
    data-twic-background="url(image:<path_to_image_1>), url(image:<path_to_image_2>)"
    data-twic-transform="none, contain"
  ></div>
</video>
```

## Medium-specific modifier attributes

While `data-twic-bot`, `data-twic-focus`, `data-twic-intrinsic`, `data-twic-step` and `data-twic-transform` are easy enough to use, they are generic and do apply to sources, posters and backgrounds indiscriminately.

To target a specific medium, simply use a more precise attribute name:

| Generic               | Source                    | Poster                       | Background                       |
| --------------------- | ------------------------- | ---------------------------- | -------------------------------- |
| `data-twic-bot`       | `data-twic-src-bot`       | `data-twic-poster-bot`       | `data-twic-background-bot`       |
| `data-twic-focus`     | `data-twic-src-focus`     | `data-twic-poster-focus`     | `data-twic-background-focus`     |
| `data-twic-intrinsic` | `data-twic-src-intrinsic` | `data-twic-poster-intrinsic` | `data-twic-background-intrinsic` |
| `data-twic-step`      | `data-twic-src-step`      | `data-twic-poster-step`      | `data-twic-background-step`      |
| `data-twic-transform` | `data-twic-src-transform` | `data-twic-poster-transform` | `data-twic-background-transform` |

<doc-alert type="info">In case both the generic modifier attribute and the medium-specific modifier attribute are set, the latter takes precedence over the former.</doc-alert>

```html
<!-- focus for source is "auto", not "25px53p" -->
<img
  data-twic-src="image:picture.jpeg"
  data-twic-focus="25px53p"
  data-twic-src-focus="auto"
/>
```

---

## API Transformations

# Transformations

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

There are two kinds of transformations: ones that actually modify the image (or video) and others that change the context of further transformations down the manipulation chain.

## Syntax

All transformations follow the same structure: `<name>=<parameters>`

where:

- `<name>` is the name of the transformation
- `<parameters>` is an expression specifying the parameters for the transformation

For instance:

- `resize=400` will resize the image to 400 pixels in width while conserving the source image aspect ratio
- `resize=640x480` will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio

## Fundamentals

<doc-alert>We refer to a list of one or several transformations as **a manipulation**.</doc-alert>

Transformations can be chained together using the character `/`. There is no limit to the number of transformations you can chain, save for the limit in size of a URL as enforced by your browser. No matter how complex the manipulation, TwicPics will optimize it for speed and accuracy on the fly.

### Focus point

Transformations behave differently depending on which point in the image is the main focus. TwicPics will do its best to keep this _focus point_ as central as possible within the transformed image.

By default, the _focus point_ is in the middle of the image but you can change its coordinates by using the <span class="api">[focus](https://www.twicpics.com/docs/reference/transformations#focus)</span> transformation.

### Chaining transformations

When adding a transformation to the chain, the parameters given are interpreted as if previous transformations had already been performed (ie. as if the source image was the result of the previous transformations).

For instance:

- `resize=340/resize=50p` will result in an image that is 170 pixel-wide
- `resize=50p/focus=20x10` will put the _focus point_ at coordinates `40x20` of the source image

Since TwicPics will optimize the manipulation, be aware that a transformation may shadow what came before it. For instance `resize=50p/resize=340` will result in an image that is 340 pixel-wide: TwicPics will simply ignore the first _resize_.

## List of transformations

### <span class="experimental">achromatopsia</span>

_Syntax_:

- <span class="api">achromatopsia=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">achro=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">achromatopsia</span>
- <span class="api">achro</span>

Corrects the colors of the image for color-blind people suffering from achromatopsia.

The _[number](https://www.twicpics.com/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](https://www.twicpics.com/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples            |                                                             |
| ------------------- | :---------------------------------------------------------: |
| _none_              | <DocSample src="colors.png"/>                               |
| `achromatopsia=0.5` | <DocSample src="colors.png" transform="achromatopsia=0.5"/> |
| `achromatopsia`     | <DocSample src="colors.png" transform="achromatopsia"/>     |

### background

_Syntax_: <span class="api">background=<[color](https://www.twicpics.com/docs/reference/parameters#color)[+[color](https://www.twicpics.com/docs/reference/parameters#color)]*></span>

_`background`_ specifies a color, or a series of colors, that will show through transparent and translucent parts of the image.

The final background color will also fill the borders created by an _[inside](#inside)_ transformation. This can be superseded by using the _[border](#border)_ transformation.

All types of [color values](https://www.twicpics.com/docs/reference/parameters#color) are accepted (i.e., `background=red`, `background=rgb(255,0,0)`, etc).

If multiple colors are specified and/or if multiple _`background`_ transformations are specified, they are applied in order using [alpha compositing](https://en.wikipedia.org/wiki/Alpha_compositing). As a consequence, if, at one point, a color is opaque, any color and or _`background`_ transformation thereafter will be ignored.

For instance, `background=red.5+white` will create a pinkish background and so will `background=red.5+white+black` and `background=red.5+white/background=black`: the final black color will be ignored because white is opaque.

Note that _background_, _[border](#border)_ and _[colorize](#colorize)_ are chainable, see [how chaining works with colors](https://www.twicpics.com/docs/reference/color-chaining) for more information.

In addition to color values, the keyword `remove` can also be used. When `remove` is found, all previous background colors will be canceled and TwicPics will remove the image background using artificial intelligence. Following that, you have a translucent image and you're free to specify a new background color.

| Examples                 |                                                                 |
| ------------------------ | :-------------------------------------------------------------: |
| _none_                   | <DocSample src="cake.png"/>                                     |
| `background=remove`      | <DocSample src="cake.png" transform="background=remove"/> |
| `background=remove+cyan` | <DocSample src="cake.png" transform="background=remove+cyan"/>  |

<doc-alert>Please note that `background=remove` is still experimental and results are subject to change.</doc-alert>

### border

_Syntax_: <span class="api">border=<[color](https://www.twicpics.com/docs/reference/parameters#color)></span>

_border_ specifies a color to fill borders eventually created by an _[inside](#inside)_ transformation. It supercedes _[background](#background)_ in that instance and it is notably possible to ensure both a solid background and translucent borders by using `border=transparent`. _border_ will have no effect on images that have no _[inside](#inside)_ applied to them.

If multiple _border_ transformations are specified, they are applied in order. If a _border_ uses an opaque color, any _border_ thereafter will be ignored.

Note that _[background](#background)_, _border_ and _[colorize](#colorize)_ are chainable, see [how chaining works with colors](https://www.twicpics.com/docs/reference/color-chaining) for more information.

### colorize

_Syntax_:

- <span class="api">colorize=<[color for black](https://www.twicpics.com/docs/reference/parameters#color)>[:<[color for white](https://www.twicpics.com/docs/reference/parameters#color)>]</span>
- <span class="api">colorize=&lt;color scheme&gt;</span>

Replaces colors in the image to create a gradient, replacing pure black with the first given color and pure white with the second given color.

| Examples              |                                                                |
| --------------------- | :------------------------------------------------------------: |
| _none_                | <DocSample src="colors.png"/>                                  |
| `colorize=black`      | <DocSample src="colors.png" transform="colorize=black"/>       |
| `colorize=black:cyan` | <DocSample src="colors.png" transform="colorize=black:cyan"/>  |
| `colorize=cyan:black` | <DocSample src="colors.png" transform="colorize=cyan:black"/>  |

There are also two available color schemes for your convenience:

- `monochrome` to create a black-and-white image
- `sepia` to create a sepia effect

| Examples              |                                                                |
| --------------------- | :------------------------------------------------------------: |
| `colorize=monochrome` | <DocSample src="colors.png" transform="colorize=monochrome"/>  |
| `colorize=sepia`      | <DocSample src="colors.png" transform="colorize=sepia"/>       |

Note that _[background](#background)_, _[border](#border)_ and _colorize_ are chainable, see [how chaining works with colors](https://www.twicpics.com/docs/reference/color-chaining) for more information.

### contain

_Syntax_: <span class="api">contain=<[size](https://www.twicpics.com/docs/reference/parameters#size)></span>

_contain_ behaves like the CSS background-size "contain". It will resize the image so that it completely fits inside the target area while conserving the original aspect ratio. The resulting image will be smaller than a target size which aspect ratio is not the same as the aspect ratio of the input.

For instance, applying `contain=150x100` to a 300x188 close-up of a cat will result in the following 150x94 image:

<DocStaticSample src="cat-300.jpg" transform="contain=150x100" width="150" height="94"></DocStaticSample>

### contain-max

_Syntax_: <span class="api">contain-max=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _contain_ that will be applied only when one of the given _lengths_ is smaller than the corresponding input image dimension.

### contain-min

_Syntax_: <span class="api">contain-min=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _contain_ that will be applied only when one of the given _lengths_ is larger than the corresponding input image dimension.

### cover

_Syntax_: <span class="api">cover=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)></span>

_cover_ behaves like the CSS background-size "cover". It will resize the image so that it completely fills the target area while conserving the original aspect ratio. If some parts of the image end up outside of the covered area, they are cropped.

So, a `cover=100x100` of a 300x188 image would first scale the image down to a height of 100 pixels and then crop along the x-axis as demonstrated below:

| Process                                                                             | Result                         |
| ----------------------------------------------------------------------------------- | ------------------------------ |
| <DocStaticSample src="cat-300-cover-center-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg"/> |

_cover_ will use the _focus point_ as a guide and will crop the image so that the _focus point_ is as central as possible in the resulting image. For instance, `focus=85x85/cover=100x100` will behave as follows:

| Process                                                                            | Result                                                               |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <DocStaticSample src="cat-300-cover-focus-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg" transform="focus=85x85/cover=100x100"/> |

When a _ratio_ is provided, _cover_ will extract the biggest possible area that satisfies the _ratio_ and is as centered on the _focus point_ as possible. For instance, `focus=85x85/cover=1:1` will behave as follows:

| Process                                                                            | Result                                                           |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| <DocStaticSample src="cat-300-cover-ratio-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg" transform="focus=85x85/cover=1:1"/> |

### cover-max

_Syntax_: <span class="api">cover-max=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _cover_ that will be applied only when one of the given _lengths_ is smaller than the corresponding input image dimension.

### cover-min

_Syntax_: <span class="api">cover-min=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _cover_ that will be applied only when one of the given _lengths_ is larger than the corresponding input image dimension.

### crop

_Syntax_: <span class="api">crop=<[crop size](https://www.twicpics.com/docs/reference/parameters#crop-size)>\[@<[coordinates](https://www.twicpics.com/docs/reference/parameters#coordinates)>\]</span>

_crop_ will extract a zone from the image which size is the given _crop size_. If no _coordinates_ are given, the _focus point_ will be used as a guide to determine where to start the extraction. If _coordinates_ are given, they will be used to determine the top-left pixel from which to start the extraction and the _focus point_ will be reset to the center of the resulting image.

| Examples             | Process                                                                             | Result             |
| -------------------- | ----------------------------------------------------------------------------------- | ------------------ |
| `crop=200x100`       | <DocStaticSample src="cat-300-crop-no-coord-process.jpg" width="300" height="188"/> | <DocStaticSample src="cat-300.jpg" transform="crop=200x100" width="200" height="100"/> |
| `crop=200x100@20x50` | <DocStaticSample src="cat-300-crop-coord-process.jpg" width="300" height="188"/>    | <DocStaticSample src="cat-300.jpg" transform="crop=200x100@20x50" width="200" height="100"/> |

### <span class="experimental">deuteranopia</span>

_Syntax_:

- <span class="api">deuteranopia=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">deut=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">deuteranopia</span>
- <span class="api">deut</span>

Corrects the colors of the image for color blind people suffering from deuteranopia.

The _[number](https://www.twicpics.com/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](https://www.twicpics.com/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples           |                                                            |
| ------------------ | :--------------------------------------------------------: |
| _none_             | <DocSample src="colors.png"/>                              |
| `deuteranopia=0.5` | <DocSample src="colors.png" transform="deuteranopia=0.5"/> |
| `deuteranopia`     | <DocSample src="colors.png" transform="deuteranopia"/>     |

### download

_Syntax_:

- <span class="api">download</span>
- <span class="api">download=&lt;basename&gt;</span>
- <span class="api">download=&lt;basename&gt;.&lt;extension&gt;</span>

Forces media to be downloaded rather than displayed in the browser when the URL containing the transformation is used as a link `href` or entered in the address bar.

When no parameter is given, filename will have a _basename_ based on the type of media (`image` or `video`) and with an _extension_ corresponding to the output format of the media (`.mp4`, `.webp`, etc).

For instance:

- `image.webp`
- `video.mp4`

If only a _basename_ is given, then the _extension_ will still correspond to the output format of the media (`.jpeg`, `.webm`, etc).

| Examples         |              |
| ---------------- | :----------: |
| `download=birds` | `birds.webm` |
| `download=road`  | `road.jpeg`  |

If both a _basename_ and an _extension_ are given they will constitute the full filename. Only use this option when you know the actual output format of the media in order to use the correct file extension.

### duration

_Syntax_: <span class="api">duration=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

If the source media is a video, _`duration`_ will extract the given duration from said source video.

Duration is a number of seconds that can be an integer as well as a real number (i.e., `duration=2`, `duration=11.2`, etc ).

By default, _`duration`_ is applied from the start of the source video. For instance, `duration=6` will effectively slice the video from the start up to second `6`. You can change this behavior by using the _[`from` transformation](#from)_.

You can find more information about _`duration`_ and its use-cases in the [video slicing](https://www.twicpics.com/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](https://www.twicpics.com/docs/guides/video-optimization).

### flip

_Syntax_: <span class="api">flip=<[axis](https://www.twicpics.com/docs/reference/parameters#axis)></span>

_flip_ will invert the image horizontally, vertically, or both, depending on the _axis_ provided.

| Expression | Axis                    |                                                      |
| ---------- | ----------------------- | :--------------------------------------------------: |
| `both`     | horizontal and vertical | <DocSample src="compass.png" transform="flip=both"/> |
| `x`        | horizontal              | <DocSample src="compass.png" transform="flip=x"/>    |
| `y`        | vertical                | <DocSample src="compass.png" transform="flip=y"/>    |

### focus

_Syntax_:

- <span class="api">focus=<[coordinates](https://www.twicpics.com/docs/reference/parameters#coordinates)></span><br>
- <span class="api">focus=<[anchor](https://www.twicpics.com/docs/reference/parameters#anchor)></span><br>
- <span class="api">focus=auto</span>

_focus_ will set the focus point coordinates. It doesn't modify the output image in any way but will change the behavior of further transformations that take the focus point into account (namely _[cover](#cover)_, _[crop](#crop)_ and _[zoom](#zoom)_).

If an _[anchor](https://www.twicpics.com/docs/reference/parameters#anchor)_ is provided, then the focus point will be the corresponding corner or the middle point of the corresponding border.

If `auto` is used in place of actual coordinates, the focus point will be chosen automagically for you! Note that `auto` is not implemented for videos yet.

### from

_Syntax_: <span class="api">from=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

If the source media is a video, _`from`_ will slice it from the given mark.

Mark is a position in seconds that can be an integer as well as a real number (i.e., `from=1`, `from=5.75`, etc).

By default, the video will be sliced up to the end of the source video. For instance, `from=2` on a 10-second long source video will effectively slice the video from second `2` to second `10`. You can change this behavior by using the _[`duration` transformation](#duration)_ or the _[`to` transformation](#to)_.

You can find more information about _`from`_ and its use-cases in the [video slicing](https://www.twicpics.com/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](https://www.twicpics.com/docs/guides/video-optimization).

### inside

_Syntax_: <span class="api">inside=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)></span>

_inside_ behaves like the CSS background-size "contain". It will resize the image so that it completely fits inside the target area. Contrary to the _[contain](#contain)_ transformation, translucent borders will be added if the resulting aspect ratio is not the same as the aspect ratio of the input so that the resulting image has the exact, physical, size specified.

If the _[background](#background)_ transformation is used, then the background color will be used to fill the borders. If you wish to have a different color than the background color for the added borders, you can use the _[border](#border)_ transformation.

| Examples                                      |                                                                                   |
| --------------------------------------------- | :-------------------------------------------------------------------------------: |
| `inside=150x150`                              | <DocStaticSample src="cat-300.jpg" transform="inside=150x150" width="150" height="150"/>                           |
| `background=black/inside=150x150`             | <DocStaticSample src="cat-300.jpg" transform="background=black/inside=150x150" width="150" height="150"/> |
| `background=black/border=cyan/inside=150x150` | <DocStaticSample src="cat-300.jpg" transform="background=black/border=cyan/inside=150x150" width="150" height="150"/>  |

### max

_Syntax_: <span class="api">max=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

Alias of <span class="api">[contain-max](#contain-max)</span>.

### min

_Syntax_: <span class="api">min=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

Alias of <span class="api">[contain-min](#contain-min)</span>.

### noop

_Syntax_: <span class="api">noop</span>

Passes the media as is. TwicPics will not re-encode or apply any transformation be they provided through the API or through the path default manipulation.

<doc-alert type="warning">
By default, TwicPics will ignore `noop` since it makes your original media available to the outside world, and that may be an unintended side-effect. As a consequence, you need to explicitly allow `noop` in your path configuration.
</doc-alert>

### output

_Syntax_:

- <span class="api">output=&lt;format&gt;</span>
- <span class="api">output=&lt;preview type&gt;</span>
- <span class="api">output=auto</span>

Specifies the output format. It can be an _image format_, a _video format_ or a _preview format_. Only the last _output_ in the manipulation expression is taken into account. By default, TwicPics will "smart-guess" the best output _format_ for the browser currently issuing the request, but you can use _output_ to override this behavior.

Available _image formats_ are:

- `avif` for [AV1 Image File Format](<https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)>)
- `heif` for [High Efficiency Image File Format](https://wikipedia.org/wiki/High_Efficiency_Image_File_Format)
- `image` (`jpeg` or `webp` depending on the browser, useful to extract the first frame of a video)
- `jpeg` for [Joint Photographic Experts Group](https://wikipedia.org/wiki/JPEG)
- `png` for [Portable Network Graphics](https://wikipedia.org/wiki/Portable_Network_Graphics)
- `webp` for [WebP](https://wikipedia.org/wiki/WebP)

Available _video formats_ are:

- `h264` for an [H.264](https://en.wikipedia.org/wiki/Advanced_Video_Coding) stream in an [MPEG-4 Part 14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) container
- `h265` for an [H.265](https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding) stream in an [MPEG-4 Part 14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) container
- `vp9` for a [VP9](https://en.wikipedia.org/wiki/VP9) stream in a [WebM](https://en.wikipedia.org/wiki/WebM) container

Available _preview types_ are:

- `blank`: a blank, totally translucent version of the resulting image
- `blurhash`: a small text-based representation of the image (see [BlurHash](https://blurha.sh))
- `maincolor`: a solid color image containing the most important color in the resulting image
- `meancolor`: a solid color image containing the mean color of the resulting image
- `preview`: a blurry preview of the resulting image

For _videos_ and by default, _previews_ are based on the first frame of the resulting video. You can use the [`from`](#from) transformation to target a specific frame.

| Preview Formats    |                                                                                          |
| ------------------ | :--------------------------------------------------------------------------------------: |
| `output=blank`     | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=blank"/>     |
| `output=maincolor` | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=maincolor"/> |
| `output=meancolor` | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=meancolor"/> |
| `output=preview`   | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=preview"/>   |
| _original image_   | <DocSample src="storm.jpeg" transform="focus=auto"/>                                     |

Please note that `blank`, `maincolor`, `meancolor` and `preview` are distributed with a `X-Robots-Tag: noindex` header so that they are not indexed by search engines.

In addition, you can use `output=auto` to ensure TwicPics' "smart-guess" of the output _format_ is used even if an output _format_ has already been specified by the [default manipulation](https://www.twicpics.com/docs/essentials/path-configuration#default-manipulation) of your path.

### <span class="experimental">protanopia</span>

_Syntax_:

- <span class="api">protanopia=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">prot=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">protanopia</span>
- <span class="api">prot</span>

Corrects the colors of the image for color-blind people suffering from protanopia.

The _[number](https://www.twicpics.com/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](https://www.twicpics.com/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples         |                                                          |
| ---------------- | :------------------------------------------------------: |
| _none_           | <DocSample src="colors.png"/>                            |
| `protanopia=0.5` | <DocSample src="colors.png" transform="protanopia=0.5"/> |
| `protanopia`     | <DocSample src="colors.png" transform="protanopia"/>     |

### quality

_Syntax_: <span class="api">quality=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

Specifies the output quality as a number between 1 and 100.

Note that `quality` will be ignored when:

- `output` is `png` and <span class="api">[truecolor](#truecolor)</span> is on
- `output` is a _preview format_

### quality-max

_Syntax_: <span class="api">quality-max=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

A conditional version of _quality_ that will be applied only when given quality is below current quality.

| Examples                     | Resulting quality |
| ---------------------------- | ----------------- |
| `quality=100/quality-max=50` | `50`              |
| `quality=20/quality-max=50`  | `20`              |
| `quality-max=50/quality=100` | `100`             |

### quality-min

_Syntax_: <span class="api">quality-min=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

A conditional version of _quality_ that will be applied only when given quality is above current quality.

| Examples                     | Resulting quality |
| ---------------------------- | ----------------- |
| `quality=100/quality-min=50` | `100`             |
| `quality=20/quality-min=50`  | `50`              |
| `quality-min=50/quality=20`  | `20`              |

### refit

_Syntax_: <span class="api">refit=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)>[@<[anchor](https://www.twicpics.com/docs/reference/parameters#anchor)>][([padding](https://www.twicpics.com/docs/reference/parameters#padding))]</span>

Alias of <span class="api">[refit-cover](#refit-cover)</span>.

### refit-cover

_Syntax_: <span class="api">refit-cover=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)>[@<[anchor](https://www.twicpics.com/docs/reference/parameters#anchor)>][([padding](https://www.twicpics.com/docs/reference/parameters#padding))]</span>

_refit-cover_ will resize the image to the specified _size_ while maximizing the area occupied by the main object (or objects) found within said image.

| Example           |                                                                                               |
| ----------------- | :-------------------------------------------------------------------------------------------: |
| original image    | <DocStaticSample src="woman-in-canyon.jpeg" transform="resize=376" width="188" height="125"/> |
| `refit-cover=1:1` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1"/>                           |

By default, the subject will be placed at the center of the resulting image but it is possible to align the subject with a given border by specifying an [anchor](https://www.twicpics.com/docs/reference/parameters#anchor).

| Examples                |                                                                           |
| ----------------------- | :-----------------------------------------------------------------------: |
| `refit-cover=1:1@left`  | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1@left"/>  |
| `refit-cover=1:1@right` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1@right"/> |

Also by default, the subject will touch the borders of the resulting image. This can be avoided by adding [padding](https://www.twicpics.com/docs/reference/parameters#padding).

It is generally easier to use padding values in percentage so that the added breathing room is independent of previous scalings.

| Examples                    |                                                                               |
| --------------------------- | :---------------------------------------------------------------------------: |
| `refit-cover=1:1`           | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1"/>           |
| `refit-cover=1:1(15p)`      | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1(15p)"/>      |
| `refit-cover=1:1(30p,0,5p)` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1(30p,0,5p)"/> |

<doc-alert type="warning">
Note that <i>refit-cover</i> will never create pixels that were not present in the original image.
<p>If there is not enough pixels in the original image to satisfy a given padding, as many pixels as available will be used and it may create a padding region that is smaller than expected.</p>
<p>If there is not enough pixels on the opposing side of the anchor point then the same best-effort approach will be used and the subject may be farther from the anchor point than expected.</p>
If placement is paramount to you, please use <em><i>refit-inside</i></em> instead.
</doc-alert>

### refit-inside

_Syntax_: <span class="api">refit-inside=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)>[@<[anchor](https://www.twicpics.com/docs/reference/parameters#anchor)>][([padding](https://www.twicpics.com/docs/reference/parameters#padding))]</span>

_refit-inside_ will resize the image to the specified _size_ while ensuring the main object (or objects) are perfectly centered, even if it means borders have to be created in the process.

| Example            |                                                                                       |
| ------------------ | :-----------------------------------------------------------------------------------: |
| original image     | <DocStaticSample src="football.jpg" transform="resize=376" width="208" height="139"/> |
| `refit-inside=1:1` | <DocSample src="football.jpg" transform="refit-inside=1:1/border=red"/>               |

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an [anchor](https://www.twicpics.com/docs/reference/parameters#anchor).

| Examples                 |                                                                               |
| ------------------------ | :---------------------------------------------------------------------------: |
| `refit-inside=1:1@left`  | <DocSample src="football.jpg" transform="refit-inside=1:1@left/border=red"/>  |
| `refit-inside=1:1@right` | <DocSample src="football.jpg" transform="refit-inside=1:1@right/border=red"/> |

Also by default, the subject will touch the borders of the resulting image. This can be avoided by adding [padding](https://www.twicpics.com/docs/reference/parameters#padding).

It is generally easier to use padding values in percentage so that the added breathing room is independent of previous scalings.

| Examples                     |                                                                                   |
| ---------------------------- | :-------------------------------------------------------------------------------: |
| `refit-inside=1:1`           | <DocSample src="football.jpg" transform="refit-inside=1:1/border=red"/>           |
| `refit-inside=1:1(15p)`      | <DocSample src="football.jpg" transform="refit-inside=1:1(15p)/border=red"/>      |
| `refit-inside=1:1(30p,0,5p)` | <DocSample src="football.jpg" transform="refit-inside=1:1(30p,0,5p)/border=red"/> |

### resize

_Syntax_: <span class="api">resize=<[size](https://www.twicpics.com/docs/reference/parameters#size)|[ratio](https://www.twicpics.com/docs/reference/parameters#ratio)></span>

_resize_ will resize the image to the specified _size_. If only one _length_ is provided, the other dimension will be determined so as to respect the aspect ratio of the input image. If both _lengths_ are provided, the aspect ratio may not be respected.

| Examples         |                                                                                          |
| ---------------- | :--------------------------------------------------------------------------------------: |
| `resize=150`     | <DocStaticSample src="cat-300.jpg" transform="resize=150" width="150" height="94"/>      |
| `resize=-x150`   | <DocStaticSample src="cat-300.jpg" transform="resize=-x150" width="239" height="150"/>   |
| `resize=150x150` | <DocStaticSample src="cat-300.jpg" transform="resize=150x150" width="150" height="150"/> |

If a _ratio_ is provided, the image will be resized so that it stays as close as possible to its current surface (i.e., number of pixels) while respecting the given aspect ratio as closely as possible.

For instance, `resize=4:3` will result in the following 274x206 image:

<DocStaticSample src="cat-300.jpg" transform="resize=4:3" width="274" height="206"></DocStaticSample>

The 300x188 image was resized to a 274x206 image (respecting the 4:3 ratio as best as possible). The initial surface was (300x188=) 56,400 pixels. The final surface is (274x206=) 56,444 pixels.

### resize-max

_Syntax_: <span class="api">resize-max=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _resize_ that will be applied only when one of the given _lengths_ is smaller than the corresponding input image dimension.

### resize-min

_Syntax_: <span class="api">resize-min=<[pixel size](https://www.twicpics.com/docs/reference/parameters#size)></span>

A conditional version of _resize_ that will be applied only when one of the given _lengths_ is larger than the corresponding input image dimension.

### to

_Syntax_: <span class="api">to=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

If the source media is a video, _`to`_ will slice it up to the given mark.

Mark is a position in seconds that can be an integer as well as a real number (i.e., `to=17`, `to=9.61`, etc ).

By default, the video will be sliced from the very start of the source video. For instance, `to=8` will effectively slice the video from the start up to second `8`. You can change this behaviour by using the _[`from` transformation](#from)_.

You can find more information about _`to`_ and its use-cases in the [video slicing](https://www.twicpics.com/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](https://www.twicpics.com/docs/guides/video-optimization).

### <span class="experimental">tritanopia</span>

_Syntax_:

- <span class="api">tritanopia=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">trit=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>
- <span class="api">tritanopia</span>
- <span class="api">trit</span>

Corrects the colors of the image for color-blind people suffering from protanopia.

The _[number](https://www.twicpics.com/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](https://www.twicpics.com/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples         |                                                          |
| ---------------- | :------------------------------------------------------: |
| _none_           | <DocSample src="colors.png"/>                            |
| `tritanopia=0.5` | <DocSample src="colors.png" transform="tritanopia=0.5"/> |
| `tritanopia`     | <DocSample src="colors.png" transform="tritanopia"/>     |

### truecolor

_Syntax_:

- <span class="api">truecolor=<[boolean](https://www.twicpics.com/docs/reference/parameters#boolean)></span>
- <span class="api">truecolor</span>

_truecolor_ can be used to prevent color quantization. If no _boolean_ is provided, `true` is assumed. By default, quantization is allowed (`truecolor=false`).

When may quantization occur? Whenever the output format is `png`. By default, TwicPics will quantize colors to reduce the size of the output image. It is possible to prevent this behaviour by setting _truecolor_ to `true`.

Be aware that TwicPics will automatically output PNG images when:

- no output format is specified,
- the source image has an alpha channel,
- and, target browser does not support WebP.

As such, use _truecolor_ if you want to distribute substantially larger but more accurate images with translucency to users on browsers that do not support WebP.

### turn

_Syntax_: <span class="api">turn=<[angle](https://www.twicpics.com/docs/reference/parameters#angle)></span>

_turn_ will change the orientation of the image. It accepts an [angle](https://www.twicpics.com/docs/reference/parameters#angle). Angles will be rounded to the closest multiple of 90°.

| Expression   |   Angle   |                                                       |
| ------------ | :-------: | :---------------------------------------------------: |
| `turn=flip`  |   180°    | <DocSample src="compass.png" transform="turn=flip"/>  |
| `turn=left`  |   -90°    | <DocSample src="compass.png" transform="turn=left"/>  |
| `turn=right` |   90°     | <DocSample src="compass.png" transform="turn=right"/> |

### zoom

_Syntax_: <span class="api">zoom=<[number](https://www.twicpics.com/docs/reference/parameters#number)></span>

Zooms into the image by a factor equal or superior to 1 towards the _focus point_ while preserving the image size.

| Examples   |                                                                            |
| ---------- | :------------------------------------------------------------------------: |
| `zoom=1`   | <DocSample src="concert.jpeg" transform="focus=57px15p"/>                                  |
| `zoom=1.5` | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=1.5"/> |
| `zoom=2`   | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=2"/>   |
| `zoom=3`   | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=3"/>   |

---

## API Parameters

# Parameters

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

For consistency, [transformations](https://www.twicpics.com/docs/reference/transformations) use the same format for parameters that represent similar underlying concepts.

## anchor

An _anchor_ represents a border or a corner of an image.

The following literals are accepted:

- `bottom`
- `bottom-left`
- `bottom-right`
- `left`
- `top`
- `top-left`
- `top-right`
- `right`

## angle

An _angle_ represents... an angle.

It can be a [number](#number) in which case it is rounded to the nearest multiple of 90 and represents an angle expressed in degrees.

The following literals are also accepted:
| Literal | Angle |
| - | -:|
| `anticlockwise` | -90° |
| `clockwise` | 90° |
| `counterclockwise` | -90° |
| `flip` | 180° |
| `left` | -90° |
| `reverse` | 180° |
| `right` | 90° |

## axis

An _axis_ represents the horizontal axis, the vertical axis or both.

The following literals are accepted:
| Literal | Axis |
| - | -:|
| `both` | both |
| `h` | horizontal |
| `horizontal` | horizontal |
| `v` | vertical |
| `vertical` | vertical |
| `x` | horizontal |
| `y` | vertical |

## boolean

A _boolean_ represents... a boolean value (true or false).

The following literals are accepted:
| Literal | Boolean |
| - | -:|
| `false` | false |
| `no` | false |
| `off` | false |
| `on` | true |
| `true` | true |
| `yes` | true |

## color

A _color_ represents... a color! It can be specified as:

- a color name like `red` or `green` (see the comprehensive list further down this section),
- a three character hexadecimal value like `76E` for RGB colors with no alpha,
- a four character hexadecimal value like `76E8` for RGB colors with alpha,
- a six character hexadecimal value like `A68040` for RGB colors with no alpha,
- a eight character hexadecimal value like `A6804080` for RGB colors with alpha,
- a CSS-like RGB expression: `rgb(<red>,<green>,<blue>)`,
- a CSS-like RGBA expression: `rgba(<red>,<green>,<blue>,<alpha>)`,
- a CSS-like HSL expression: `hsl(<hue>,<saturation>,<lightness>)`,
- a CSS like HSLA expression: `hsla(<hue>,<saturation>,<lightness>,<alpha>)`.

TwicPics also adds `transparent` so that you can easily create an invisible [placeholder](https://www.twicpics.com/docs/reference/placeholders) using `placeholder:transparent`.

Finally, you also have the possibility to add an alpha value to color names, three character hexadecimal colors, and six character hexadecimal color. Simply append the decimal part of the alpha component to the color expression.

| Examples    |                               |
| :---------- | :---------------------------: |
| `violet.25` | <DocColor value="violet.25"/> |
| `008.75`    | <DocColor value="008.75"/>    |
| `808080.3`  | <DocColor value="808080.3"/>  |

Finally, here is the list of all supported color names:

| Name                     | Preview                                    |
| :----------------------- | :----------------------------------------: |
| `alice-blue`             | <DocColor value="alice-blue"/>             |
| `antique-white`          | <DocColor value="antique-white"/>          |
| `aqua`                   | <DocColor value="aqua"/>                   |
| `aquamarine`             | <DocColor value="aquamarine"/>             |
| `azure`                  | <DocColor value="azure"/>                  |
| `beige`                  | <DocColor value="beige"/>                  |
| `bisque`                 | <DocColor value="bisque"/>                 |
| `black`                  | <DocColor value="black"/>                  |
| `blanched-almond`        | <DocColor value="blanched-almond"/>        |
| `blue`                   | <DocColor value="blue"/>                   |
| `blue-violet`            | <DocColor value="blue-violet"/>            |
| `brown`                  | <DocColor value="brown"/>                  |
| `burlywood`              | <DocColor value="burlywood"/>              |
| `cadet-blue`             | <DocColor value="cadet-blue"/>             |
| `chartreuse`             | <DocColor value="chartreuse"/>             |
| `chocolate`              | <DocColor value="chocolate"/>              |
| `coral`                  | <DocColor value="coral"/>                  |
| `cornflower-blue`        | <DocColor value="cornflower-blue"/>        |
| `cornsilk`               | <DocColor value="cornsilk"/>               |
| `crimson`                | <DocColor value="crimson"/>                |
| `cyan`                   | <DocColor value="cyan"/>                   |
| `dark-blue`              | <DocColor value="dark-blue"/>              |
| `dark-cyan`              | <DocColor value="dark-cyan"/>              |
| `dark-goldenrod`         | <DocColor value="dark-goldenrod"/>         |
| `dark-gray`              | <DocColor value="dark-gray"/>              |
| `dark-green`             | <DocColor value="dark-green"/>             |
| `dark-khaki`             | <DocColor value="dark-khaki"/>             |
| `dark-magenta`           | <DocColor value="dark-magenta"/>           |
| `dark-olive-green`       | <DocColor value="dark-olive-green"/>       |
| `dark-orange`            | <DocColor value="dark-orange"/>            |
| `dark-orchid`            | <DocColor value="dark-orchid"/>            |
| `dark-red`               | <DocColor value="dark-red"/>               |
| `dark-salmon`            | <DocColor value="dark-salmon"/>            |
| `dark-sea-green`         | <DocColor value="dark-sea-green"/>         |
| `dark-slate-blue`        | <DocColor value="dark-slate-blue"/>        |
| `dark-slate-gray`        | <DocColor value="dark-slate-gray"/>        |
| `dark-turquoise`         | <DocColor value="dark-turquoise"/>         |
| `dark-violet`            | <DocColor value="dark-violet"/>            |
| `deep-pink`              | <DocColor value="deep-pink"/>              |
| `deep-sky-blue`          | <DocColor value="deep-sky-blue"/>          |
| `dim-gray`               | <DocColor value="dim-gray"/>               |
| `dodger-blue`            | <DocColor value="dodger-blue"/>            |
| `firebrick`              | <DocColor value="firebrick"/>              |
| `floral-white`           | <DocColor value="floral-white"/>           |
| `forest-green`           | <DocColor value="forest-green"/>           |
| `fuchsia`                | <DocColor value="fuchsia"/>                |
| `gainsboro`              | <DocColor value="gainsboro"/>              |
| `ghost-white`            | <DocColor value="ghost-white"/>            |
| `gold`                   | <DocColor value="gold"/>                   |
| `goldenrod`              | <DocColor value="goldenrod"/>              |
| `gray`                   | <DocColor value="gray"/>                   |
| `green`                  | <DocColor value="green"/>                  |
| `green-yellow`           | <DocColor value="green-yellow"/>           |
| `honeydew`               | <DocColor value="honeydew"/>               |
| `hot-pink`               | <DocColor value="hot-pink"/>               |
| `indian-red`             | <DocColor value="indian-red"/>             |
| `indigo`                 | <DocColor value="indigo"/>                 |
| `ivory`                  | <DocColor value="ivory"/>                  |
| `khaki`                  | <DocColor value="khaki"/>                  |
| `lavender`               | <DocColor value="lavender"/>               |
| `lavender-blush`         | <DocColor value="lavender-blush"/>         |
| `lawn-green`             | <DocColor value="lawn-green"/>             |
| `lemon-chiffon`          | <DocColor value="lemon-chiffon"/>          |
| `light-blue`             | <DocColor value="light-blue"/>             |
| `light-coral`            | <DocColor value="light-coral"/>            |
| `light-cyan`             | <DocColor value="light-cyan"/>             |
| `light-goldenrod-yellow` | <DocColor value="light-goldenrod-yellow"/> |
| `light-gray`             | <DocColor value="light-gray"/>             |
| `light-green`            | <DocColor value="light-green"/>            |
| `light-pink`             | <DocColor value="light-pink"/>             |
| `light-salmon`           | <DocColor value="light-salmon"/>           |
| `light-sea-green`        | <DocColor value="light-sea-green"/>        |
| `light-sky-blue`         | <DocColor value="light-sky-blue"/>         |
| `light-slate-gray`       | <DocColor value="light-slate-gray"/>       |
| `light-steel-blue`       | <DocColor value="light-steel-blue"/>       |
| `light-yellow`           | <DocColor value="light-yellow"/>           |
| `lime`                   | <DocColor value="lime"/>                   |
| `lime-green`             | <DocColor value="lime-green"/>             |
| `linen`                  | <DocColor value="linen"/>                  |
| `magenta`                | <DocColor value="magenta"/>                |
| `maroon`                 | <DocColor value="maroon"/>                 |
| `medium-aquamarine`      | <DocColor value="medium-aquamarine"/>      |
| `medium-blue`            | <DocColor value="medium-blue"/>            |
| `medium-orchid`          | <DocColor value="medium-orchid"/>          |
| `medium-purple`          | <DocColor value="medium-purple"/>          |
| `medium-sea-green`       | <DocColor value="medium-sea-green"/>       |
| `medium-slate-blue`      | <DocColor value="medium-slate-blue"/>      |
| `medium-spring-green`    | <DocColor value="medium-spring-green"/>    |
| `medium-turquoise`       | <DocColor value="medium-turquoise"/>       |
| `medium-violet-red`      | <DocColor value="medium-violet-red"/>      |
| `midnight-blue`          | <DocColor value="midnight-blue"/>          |
| `mint-cream`             | <DocColor value="mint-cream"/>             |
| `misty-rose`             | <DocColor value="misty-rose"/>             |
| `moccasin`               | <DocColor value="moccasin"/>               |
| `navajo-white`           | <DocColor value="navajo-white"/>           |
| `navy`                   | <DocColor value="navy"/>                   |
| `old-lace`               | <DocColor value="old-lace"/>               |
| `olive`                  | <DocColor value="olive"/>                  |
| `olive-drab`             | <DocColor value="olive-drab"/>             |
| `orange`                 | <DocColor value="orange"/>                 |
| `orange-red`             | <DocColor value="orange-red"/>             |
| `orchid`                 | <DocColor value="orchid"/>                 |
| `pale-goldenrod`         | <DocColor value="pale-goldenrod"/>         |
| `pale-green`             | <DocColor value="pale-green"/>             |
| `pale-turquoise`         | <DocColor value="pale-turquoise"/>         |
| `pale-violet-red`        | <DocColor value="pale-violet-red"/>        |
| `papaya-whip`            | <DocColor value="papaya-whip"/>            |
| `peach-puff`             | <DocColor value="peach-puff"/>             |
| `peru`                   | <DocColor value="peru"/>                   |
| `pink`                   | <DocColor value="pink"/>                   |
| `plum`                   | <DocColor value="plum"/>                   |
| `powder-blue`            | <DocColor value="powder-blue"/>            |
| `purple`                 | <DocColor value="purple"/>                 |
| `rebecca-purple`         | <DocColor value="rebecca-purple"/>         |
| `red`                    | <DocColor value="red"/>                    |
| `rosy-brown`             | <DocColor value="rosy-brown"/>             |
| `royal-blue`             | <DocColor value="royal-blue"/>             |
| `saddle-brown`           | <DocColor value="saddle-brown"/>           |
| `salmon`                 | <DocColor value="salmon"/>                 |
| `sandy-brown`            | <DocColor value="sandy-brown"/>            |
| `sea-green`              | <DocColor value="sea-green"/>              |
| `seashell`               | <DocColor value="seashell"/>               |
| `sienna`                 | <DocColor value="sienna"/>                 |
| `silver`                 | <DocColor value="silver"/>                 |
| `sky-blue`               | <DocColor value="sky-blue"/>               |
| `slate-blue`             | <DocColor value="slate-blue"/>             |
| `slate-gray`             | <DocColor value="slate-gray"/>             |
| `snow`                   | <DocColor value="snow"/>                   |
| `spring-green`           | <DocColor value="spring-green"/>           |
| `steel-blue`             | <DocColor value="steel-blue"/>             |
| `tan`                    | <DocColor value="tan"/>                    |
| `teal`                   | <DocColor value="teal"/>                   |
| `thistle`                | <DocColor value="thistle"/>                |
| `tomato`                 | <DocColor value="tomato"/>                 |
| `turquoise`              | <DocColor value="turquoise"/>              |
| `violet`                 | <DocColor value="violet"/>                 |
| `wheat`                  | <DocColor value="wheat"/>                  |
| `white`                  | <DocColor value="white"/>                  |
| `white-smoke`            | <DocColor value="white-smoke"/>            |
| `yellow`                 | <DocColor value="yellow"/>                 |
| `yellow-green`           | <DocColor value="yellow-green"/>           |

## coordinates

_Coordinates_ represent a point in an image, specified as a couple of **positive** <span class="api">[lengths](#length)</span> separated by the character `x`:

- the first _length_ is the coordinate along the x-axis (following the width of the image)
- the second _length_ is the coordinate along the y-axis (following the height of the image)

TwicPics uses the same coordinate system as CSS: zero-based, left-to-right and top-to-bottom.

If we take the example of an image that is 640 pixel-wide and 480 pixel-high:

- `0x0` points to the top-left corner pixel
- `639x479` points to the bottom-right corner pixel.

<doc-alert type="info">It is perfectly fine to mix _lengths_ of different _units_ in the same _coordinates_. For instance, in the context of yet another 640 per 480 sample image, _coordinates_ `100x50p` actually translate to `100x240`.</doc-alert>

## crop size

A _crop size_ is a <span class="api">[size](#size)</span> where omitted dimensions are assumed to be the same as the input image.

For instance:

- `320` and `320x-` are equivalent to `320x1s`
- `-x240` is equivalent to `1sx240`

## length

TwicPics _lengths_ are equivalent to CSS length values. They consist of a <span class="api">[number](#number)</span> eventually followed by a _unit_ specifier:

- when no _unit_ is specified, the _length_ is in _pixels_, for instance `50` is a _pixel length_ that can be read as "50 pixels"
- with the _unit_ specifier "s", the _length_ is a _scale_, for instance `(1/3)s` is a _scale length_ that can be read as "one third"
- with the _unit_ specifier "p", the _length_ is a _percentage_, for instance `4.5p` is a _percentage length_ representing "4.5%"

## number

TwicPics _numbers_ can be JSON-encoded number literals or expressions that, when computed, result in an actual number. Expressions are embedded in parenthesis. Operators `+`, `-`, `*` and `/` are supported for additions, subtractions, multiplications and divisions respectively. Classic algebraic precedence is respected and parenthesis can be used to circumvent it.

For instance, `50`, `7.2`, `(1/3)`, `(5*(7+2)/3)` are all valid _numbers_.

## padding

A _padding_ is a list of comma-separated [lengths](#length) that follows the CSS convention:
- `<top>,<right>,<bottom>,<left>`
- `<top>,<horizontal>,<bottom>`
- `<vertical>,<horizontal>`
- `<both>`

For instance, `10,100,23,47`, `0,25p`, `(1/3)s` are all valid _paddings_.

## ratio

A _ratio_ represents the proportional relationship between a width and a height. It is specified as a couple of **strictly positive** <span class="api">[numbers](#number)</span> separated by the character `:`:

- the first _number_ is the number of length units contained in the width
- the second _number_ is the number of length units contained in the height

For instance, the _ratio_ `9:3` indicates that the width is 9-units long while the height is 3-units long. In terms of proportions, the width is (9/3=)3 times longer than the height.

## size

A _size_ represents a 2D area, specified as a couple of **strictly positive** <span class="api">[lengths](#length)</span> separated by the character `x`:

- the first _length_ is the width of the area
- the second _length_ is the height of the area

For instance `640x480` is 640 pixel-wide per 480 pixel-high.

It is possible to omit one of the dimensions using the character `-`. In that case, TwicPics will automatically compute the missing dimension so that the size respects the aspect ratio of the source image. For instance, if the source image is 640 pixel-wide per 480 pixel-high, then _sizes_ `320x-` and `-x240` are both equivalent to `320x240`.

As a shortcut, it is possible to omit the height by specifying just a width. For instance, the _size_ `320` is equivalent to `320x-`.

<doc-alert type="info">It is totally legal to mix _lengths_ of different _units_ in the same _size_. For instance, `10px150` is a perfectly valid size.</doc-alert>

---

## Color chaining

# Color chaining

> How color-related transformations, overlays and masks interact.

TwicPics provides seven color-related transformations:

- three direct coloring transformations:
  - [background](https://www.twicpics.com/docs/reference/transformations#background)
  - [border](https://www.twicpics.com/docs/reference/transformations#border)
  - [colorize](https://www.twicpics.com/docs/reference/transformations#colorize)
- four colorblindness filters:
  - [achromatopsia](https://www.twicpics.com/docs/reference/transformations#achromatopsia)
  - [deuteranopia](https://www.twicpics.com/docs/reference/transformations#deuteranopia)
  - [protanopia](https://www.twicpics.com/docs/reference/transformations#protanopia)
  - [tritanopia](https://www.twicpics.com/docs/reference/transformations#colorize)

In addition, it is possible to add both a [mask](https://www.twicpics.com/docs/essentials/path-configuration#mask) and an [overlay](https://www.twicpics.com/docs/essentials/path-configuration#overlay) in your [path configuration](https://www.twicpics.com/docs/essentials/path-configuration).

## Direct coloring transformations

Like any other transformation in the TwicPics API, the order of [background](https://www.twicpics.com/docs/reference/transformations#background), [border](https://www.twicpics.com/docs/reference/transformations#border), and [colorize](https://www.twicpics.com/docs/reference/transformations#colorize) transformations in your manipulation is respected:

- `border=red/colorize=monochrome` will colorize the given [border](https://www.twicpics.com/docs/reference/transformations#border) and the end result will be a dark gray border color,
- `colorize=monochrome/border=red` will not colorize the given [border](https://www.twicpics.com/docs/reference/transformations#border) because it's specified __after__ the [colorize](https://www.twicpics.com/docs/reference/transformations#colorize) transformation and thus, the end result will be a red border color.

Same goes for the [background](https://www.twicpics.com/docs/reference/transformations#background) transformation.

Multiple [colorize](https://www.twicpics.com/docs/reference/transformations#colorize) transformations will be applied in order.

## Mask

Translucency created by the [mask](https://www.twicpics.com/docs/essentials/path-configuration#mask) is considered as _border_ and will be filled with:

- the end [border](https://www.twicpics.com/docs/reference/transformations#border) color if provided,
- otherwise the end [background](https://www.twicpics.com/docs/reference/transformations#border) color if provided,
- otherwise it will simply stay translucent.

## Overlay

The [overlay](https://www.twicpics.com/docs/essentials/path-configuration#overlay) is added after:

- any direct coloring transformation ([background](https://www.twicpics.com/docs/reference/transformations#background), [border](https://www.twicpics.com/docs/reference/transformations#border), and [colorize](https://www.twicpics.com/docs/reference/transformations#colorize)) has been applied,
- and the [mask](https://www.twicpics.com/docs/essentials/path-configuration#mask) has been applied.

The [overlay](https://www.twicpics.com/docs/essentials/path-configuration#overlay) is thus immune to colorization and masking.

## Colorblindness filters

Colorblindness filters ([achromatopsia](https://www.twicpics.com/docs/reference/transformations#achromatopsia), [deuteranopia](https://www.twicpics.com/docs/reference/transformations#deuteranopia), [protanopia](https://www.twicpics.com/docs/reference/transformations#protanopia), and [tritanopia](https://www.twicpics.com/docs/reference/transformations#colorize)) are _"global"_ and applied at the very end of our image processing process, so after:

- every [background](https://www.twicpics.com/docs/reference/transformations#background), [border](https://www.twicpics.com/docs/reference/transformations#border), and [colorize](https://www.twicpics.com/docs/reference/transformations#colorize) transformation has been applied,
- the [mask](https://www.twicpics.com/docs/essentials/path-configuration#mask) has been applied,
- and the [overlay](https://www.twicpics.com/docs/essentials/path-configuration#overlay) has been added in.

---

## Placeholders API

# Placeholders

> The complete reference for the TwicPics placeholders API.

Every [manipulation](transformations#fundamentals) can target a _placeholder_. In that case, TwicPics will compute the final dimensions consequential to the transformations then respond with an SVG image of these dimensions that also displays said dimensions.

## Examples

| Example                                     |                                                      Result                                                      |
| :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------: |
| `cover=1:1/resize=150/placeholder:auto`     |      ![cover=1:1/resize=150/placeholder:auto](https://i.twic.pics/v1/cover=1:1/resize=150/placeholder:auto)      |
| `resize=150x100/placeholder:rgb(128,0,128)` | ![resize=150x100/placeholder:rgb(128,0,128)](<https://i.twic.pics/v1/resize=150x100/placeholder:rgb(128,0,128)>) |
| `placeholder:200x100:medium-violet-red`     |      ![placeholder:200x100:medium-violet-red](https://i.twic.pics/v1/placeholder:200x100:medium-violet-red)      |

## Syntax

A placeholder follows the following syntax: <code><span class="api">placeholder:[<[dimensions](#dimensions)>:]&lt;[colors](#colors)&gt;</span></code>

### Alternative URL format

Using placeholders requires using the following alternative API URL format:

```
https://<sub>.twic.pics/v1/[<manipulation>/]<source_image>
```

where `<source_image>` is a placeholder expression of the form `placeholder:<...>`.

For instance, `https://<sub>.twic.pics/v1/resize=640x480/placeholder:auto` will generate a 640 pixels wide per 480 pixels high gray colored placeholder.

<doc-alert>This alternate URL format is also used internally by [TwicPics Native](https://www.twicpics.com/docs/essentials/native).
</doc-alert>

### Working with absolute URLs for paths

If you [used absolute URLs as paths](https://www.twicpics.com/docs/essentials/path-configuration#using-absolute-urls) in your domain configuration, you can use:

- absolute `http:` and/or `https:` URLs, provided they have corresponding paths in your domain
- relative URLs, provided they convert to absolute URLs that have corresponding paths in your domain

## Dimensions

Specifying the dimensions of a placeholder is optional. Syntax is `<width>x<height>` where `width` and `height` are strictly positive [numbers](https://www.twicpics.com/docs/reference/parameters#number).

It is perfectly valid to create a placeholder with dimensions and no color. In that case, the default colors will be used.

| Example               |                               Result                               |
| :-------------------- | :----------------------------------------------------------------: |
| `placeholder:200x150` | ![placeholder:200x150](https://i.twic.pics/v1/placeholder:200x150) |

<doc-alert type="info">If not specified, the dimensions of a placeholder default to 1920x1080.</doc-alert>

Keep in mind the final dimensions of a placeholder depends on the transformations applied to it. So `resize=(1/10)s/placeholder:auto` will give a placeholder which dimensions are 192 per 108, a tenth of the default ones.

| Example                           |                                            Result                                            |
| :-------------------------------- | :------------------------------------------------------------------------------------------: |
| `resize=(1/10)s/placeholder:auto` | ![resize=(1/10)s/placeholder:auto](<https://i.twic.pics/v1/resize=(1/10)s/placeholder:auto>) |

## Colors

Specifying the colors of a placeholder is mandatory unless dimensions have been specified. Syntax is `[<text>/]background` where `text` and `background` are [color expressions](https://www.twicpics.com/docs/reference/parameters#color) to be used for the text and the background of the image respectively.

| Example                       |                                       Result                                       |
| :---------------------------- | :--------------------------------------------------------------------------------: |
| `placeholder:50x50:white/red` | ![placeholder:50x50:white/red](https://i.twic.pics/v1/placeholder:50x50:white/red) |

<doc-alert type="info">If no text color is provided, TwicPics will choose a brightened or darkened version of the background color, whichever yields the best contrast. For a quick placeholder, just use `auto` as the color expression and TwicPics will default to an unobtrusive gray color scheme.</doc-alert>

| Example                    |                                    Result                                    |
| :------------------------- | :--------------------------------------------------------------------------: |
| `placeholder:50x50:orange` | ![placeholder:50x50:orange](https://i.twic.pics/v1/placeholder:50x50:orange) |
| `placeholder:50x50:black`  |  ![placeholder:50x50:black](https://i.twic.pics/v1/placeholder:50x50:black)  |
| `placeholder:50x50:auto`   |   ![placeholder:50x50:auto](https://i.twic.pics/v1/placeholder:50x50:auto)   |

---


---

# Guides

## Image Best Practices

# Image Best Practices

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

## Critical Images

We recommend using the **`TwicPicture`** component for critical images as it involves the native `picture` element under the hood.

```html
<TwicPicture
  src="your-master-image.jpg"
  ratio="3/4, @md 1, @xl 16/9"
/>
```

In case you're not using any JS framework client-side, we recommend using **native responsive images** combined with the **TwicPics API** for images that are displayed at the top of the page. The `picture` element with an `img` fallback is the best choice in this case.

By [writing API requests](https://www.twicpics.com/docs/essentials/api), you can easily create responsive variants of your images.

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

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

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

  <img src="https://<sub>.twic.pics/asset.jpg?twic=v1/cover=16:9/resize=1024" />
</picture>
```

<doc-alert type="info">This type of asset can also leverage the `<link rel=preload>` declarative fetch feature and the `fetchpriority` attribute.</doc-alert>

## Lazy-load off-screen media

Off-screen or content images are ideal candidates for **[TwicPics Components](https://www.twicpics.com/docs/essentials/components)** and **[TwicPics Native](https://www.twicpics.com/docs/essentials/native)**. Your assets will be automatically resized and **lazy-loaded by default**.

However, the **`<TwicImg>` component** offers many benefits out-of-the-box, like **optimized Cumulative Layout Shift (CLS)**, **aspect-ratio modifier**, **Low-Quality Image Placeholder (LQIP)**, or **transitions**:

```html
<TwicImg src="your-image.jpg" 
         mode="cover" 
         ratio="4/3" 
         placeholder="preview" 
         transition="fade"
/>
```

<doc-alert type="info">This approach is particularly well adapted for picture grids.</doc-alert>

With **TwicPics Native**, you can achieve the same result even if it requires more effort and CSS knowledge.

Here is an `HTML / CSS` example template to integrate `LQIP` and `CLS` optimization into your websites using **TwicPics Native**:

```html
<head>
  <!-- Twicpics script installation -->
  <script src="https://<your-own-twicpics-domain>/?v1" async defer></script>
</head>
<style>
  /* required when using the padding-trick */
  .isolation {
    overflow: hidden;
  }
  .media,
  .placeholder {
    /* reset border, margin and padding */
    border: none;
    margin: 0;
    padding: 0;
    /* preview and final image must stack and fill their container */
    height: 100%;
    left: 0;
    position: absolute;
    top: 0;
    width: 100%;
  }
  .media {
    object-fit: var(--twic-mode, cover);
  }
  .placeholder {
    background: no-repeat; 
    background-position: center; 
    background-size: var(--twic-mode, cover);
    opacity: 1;
    transition-property: opacity; /* makes transition smooth */
    transition-duration: var(
      --twic-duration,
      400ms
    ); /* makes transition smooth */
    will-change: opacity; /* makes transition smooth */
  }
  .media.twic-done + .placeholder {
    opacity: 0; /* hides placeholder once image is loaded */
  }
  .cls-optimization {
    overflow: hidden; /* allows border-radius for example */
    position: relative;
    padding-top: calc(
      100% / var(--twic-ratio, 1)
    ); /* padding trick : reserves the display size */
    width: 100%;
  }
  .cls-optimization img:not([src]) {
    /* avoid broken images */
    visibility: hidden;
  }

  /* YOUR OWN CSS */
  .a-custom-class {
    --twic-duration: calc(500ms); 
    --twic-mode: cover; 
    --twic-ratio: calc(4/3);
  }

</style>
<body>
  <div class="isolation a-custom-class">
    <!-- makes the template work even in display:grid -->
    <div class="cls-optimization">
      <img class="media" data-twic-src="image:<your-asset>.jpg" />
      <div
        class="placeholder" 
        style="background-image:url(https://<your-own-twicpics-domain>/<your-asset>.jpg?twic=v1/output=<preview|main|mean>);"
    ></div>
    </div>
  </div>
</body>
```

<doc-alert type="info">
To learn more about this template, read our [CLS optimization and LQIP implementation](https://www.twicpics.com/blog/how-to-easily-cls-and-lqip) blog post.
</doc-alert>

---

## TwicPics Native Quick Start Guide

# 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](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/docs/essentials/native#step) or [locally](https://www.twicpics.com/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](https://www.twicpics.com/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](https://www.twicpics.com/docs/reference/transformations#chaining-transformations) is used here so that [ratios](https://www.twicpics.com/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`](https://www.twicpics.com/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](https://www.twicpics.com/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!

---

## TwicPics Native Examples and Use Cases

# TwicPics Native Examples and Use Cases

> We have compiled a number of examples and use cases to get you started with TwicPics Native.

## Responsive Images Carousel

A pixel-perfect **responsive carousel** with **TwicPics** and [Slick](http://kenwheeler.github.io/slick/).

<code-pen id="pWeBym" title="Responsive Carousel with Slick and TwicPics"></code-pen>

## Responsive Images Gallery

This use case shows how simple it is to implement a responsive, **pixel-perfect** image grid with **TwicPics Native**. It also shows how to implement the **LQIP / Blurry Image Placeholder** pattern.

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

## Highly Performant Layout

This example combines multiple techniques to illustrate how powerful TwicPics can be. While the code is short and readable, both page performance and image quality are best-in-class.

<code-pen id="jZVMJG" title="TwicPics Best Practices"></code-pen>

---

## Video Optimization

# Video Optimization

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

TwicPics videos are short, muted, auto-playing native HTML video elements. They enable integration of hero, product, and thumbnail videos.

## Overview

TwicPics aims at making video integration as simple as integrating images.

To that end, we implement a set of defaults to maximize performance and encourage best practices. The following default values apply to video medias:

- Default [step](https://www.twicpics.com/docs/essentials/native#step) of `100`
- Output with a [quality](https://www.twicpics.com/docs/reference/transformations#quality) of `70`.

To better address video-specific optimization concerns, we introduced the [`data-twic-intrinsic` attribute](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic) (or `instrisic` prop in [components](https://www.twicpics.com/docs/essentials/components)) to prevent upscaling and limit the number of variants generated.

### Limitations

The following limitations apply to the _source video_ files that TwicPics can optimize:

- Duration: 900 frames (30 seconds at 30fps, 37.5 seconds at 24fps)
- FPS: no limit though we recommend using 24fps which is plenty enough for the web and allows for longer videos (TwicPics will __not__ modify the frame rate of videos)
- Pixels: 36 millions
- Weight: 36MB

## How It Works

In the example below, we set the URL of the original file in the `data-twic-src` attribute, define our CSS rules, and let TwicPics take care of the rest. The script generates all necessary API requests to optimize the video and adds the `<source>` elements in the correct order to ensure both browser compatibility and optimal quality.

<doc-alert>
The example below uses the vanilla JS script to generate videos, but since the components actually install the script, the output code would be similar.
</doc-alert>

**Source code**

```html
<!-- index.html -->
<div class="video-container">
  <video data-twic-src="image:video/skater.mp4"></video>
</div>
```

```css
/* style.css */
.video-container {
  position: relative;
  padding-top: calc(height / width * 100%);
  width: 100%;
}

video {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
}
```

**Output code**

```html
<!-- index.html after TwicPics has run -->
<div class="video-container">
  <video
    data-twic-src="image:video/skater.mp4"
    class=" twic-done"
    muted
    autoplay
    loop
    playsinline
  >
    <source
      src="https://demo.twic.pics/video/skater.mp4?twic=v1/cover=800x1040/output=h265"
      type="video/mp4;codecs=hvc1"
    />
    <source
      src="https://demo.twic.pics/video/skater.mp4?twic=v1/cover=800x1040/output=vp9"
      type="video/webm;codecs=vp9"
    />
    <source
      src="https://demo.twic.pics/video/skater.mp4?twic=v1/cover=800x1040/output=h264"
    />
  </video>
</div>
```

<doc-alert>As you can see, it is not necessary to fill in the `muted`, `autoplay`, `loop` and `playsinline` attributes on your `<video>` elements. TwicPics adds them automatically to reproduce the behavior of GIFs.</doc-alert>

Note that your videos will never be resized beyond their original dimensions. This integration is therefore sufficient for most of your videos, especially product or thumbnail videos. For hero videos that are the Largest Contentful Paint element of your page, read our [handling LCP videos](https://www.twicpics.com/docs/guides/handling-lcp-videos) guide.

## Generating Posters

You can manually create video posters by using the TwicPics API. The [`output=image` transformation](https://www.twicpics.com/docs/reference/transformations#output) extracts the first frame of a video and transforms it to an image. When using `data-twic-poster`, this transformation is requested by default.

```html
<video
  data-twic-poster="media:video.mp4"
  data-twic-src="media:video.mp4"
></video>
```

**Example:**

- Original video: [make-my-lemonade-1.mp4](https://assets.twicpics.com/videos/demo-twicpics/apparel-and-fashion/make-my-lemonade-1.mp4)
- Generated poster: [/make-my-lemonade-1.mp4?twic=v1/output=image](https://demo.twic.pics/video/apparel-and-fashion/make-my-lemonade-1.mp4?twic=v1/output=image)

<doc-alert>Using `output=image` lets TwicPics choose the best image format based on browser compatibility. It is also possible to force the output, eg. `output=png`.</doc-alert>

By default, the poster is based on the first frame of the source video. The very next section will show you how to use the [`from` transformation](https://www.twicpics.com/docs/reference/transformations#from) to change this behaviour.

## Video Slicing

The TwicPics API features three transformations that can be used to extract a portion of the original video:

- [`from`](https://www.twicpics.com/docs/reference/transformations#from) to set when the portion should start from,
- [`to`](https://www.twicpics.com/docs/reference/transformations#to) to set when the portion should stop,
- [`duration`](https://www.twicpics.com/docs/reference/transformations#duration), an alternative to [`to`](https://www.twicpics.com/docs/reference/transformations#to) that sets how long the portion should be.

All three transformations accepts numbers in seconds. For instance `from=2.5/duration=1.5` will extract the portion of the original vidéo from the frame at the `2.5` second mark up to the frame at the `4` second mark.

For all intents and purposes, `from=2.5/duration=1.5` is strictly equivalent to `from=2.5/to=4`.

One immediate use-case for these transformations is to extract a specific frame of the video to be used as a poster.

The following example will start the video at the `5` second mark and will use the frame at the `5` second mark as a poster.

```html
<video
  data-twic-poster="media:video.mp4"
  data-twic-src="media:video.mp4"
  data-twic-transform="*/from=5"
></video>
```

One big issue with the example above is that both the video and the poster are impacted. If you wish to keep the entire video and still use the frame at the `5` second mark as a poster, you'd use the `data-twic-poster-transform` attribute so that the `from` transformation is only applied to the poster:

```html
<video
  data-twic-poster="media:video.mp4"
  data-twic-poster-transform="*/from=5"
  data-twic-src="media:video.mp4"
></video>
```

You could also extract a portion of the video at the same time by using the `data-twic-src-transform` attribute like so:

```html
<video
  data-twic-poster="media:video.mp4"
  data-twic-poster-transform="*/from=5/output=image"
  data-twic-src="media:video.mp4"
  data-twic-src-transform="*/from=3/duration=6"
></video>
```

Here, the poster is taken at the `5` second mark while the video is an extract from second `3` up to second `9`.

## Using GIFs sources

TwicPics can convert your heavy GIF files into lightweight videos. When retrieving an animated GIF file on a video path, TwicPics will automatically convert it to a modern video format. All usual [transformations](https://www.twicpics.com/docs/reference/transformations) can be used when transforming GIFs this way.

<doc-alert>When transforming GIFs, you don't need to use `output=<codec>` transformation. GIFs transformed in videos default to MP4 format.</doc-alert>

This [demo website](https://codepen.io/twicpics/pen/JjyqazK) demonstrates an example of the performance gains when transforming a GIF file to a video file.

## Formats & Codecs Support

### Formats

While TwicPics accepts your original videos in all formats, we optimize and deliver your videos:

- in __MP4__ format (codecs `h265` and `h264`)
- in __WebM__ format (codec `vp9`)

TwicPics applies these formats and codecs so that your videos can be played by all browsers, depending on their compatibility (see [Can I Use](https://caniuse.com/) for more information).

To help you quickly produce your videos in different formats compatible with each browser, the TwicPics API offers the `output=<codec>` transformation.

### Codecs

TwicPics supports the following codecs:

#### h265

_Transformation syntax_: `output=h265`

- generates a video in __MP4__ format
- the `type` attribute of the `<source>` element must be: `type="video/mp4;codecs=hvc1"`
- compatible with Safari only

```html
<video>
  <source
    src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=h265"
    type="video/mp4;codecs=hvc1"
  />
</video>
```

#### vp9

_Transformation syntax_: `output=vp9`

- generates a video in __WebM__ format
- the `type` attribute of the `<source>` element must be: `type="video/webm;codecs=vp9"`
- not compatible with Safari

```html
<video>
  <source
    src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=vp9"
    type="video/webm;codecs=vp9"
  />
</video>
```

#### h264

_Transformation syntax_: `output=h264`

- generates a video in __MP4__ format
- no `type` attribute required
- compatible with all browsers

```html
<video>
  <source src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=h264" />
</video>
```

Below is a complete example of integrating a video with the TwicPics API, according to the order recommended for the declaration of the `<source>` elements and the different supported codecs:

```html
<video muted autoplay loop playsinline>
  <!-- compatible with Safari only -->
  <source
    src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=h265"
    type="video/mp4;codecs=hvc1"
  />
  <!-- not compatible with Safari -->
  <source
    src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=vp9"
    type="video/webm;codecs=vp9"
  />
  <!-- compatible with all browsers -->
  <source src="https://demo.twic.pics/video/skater.mp4?twic=v1/output=h264" />
</video>
```

<doc-alert>We recommend using the __muted__, __autoplay__, __loop__, and __playsinline__ attributes when using the TwicPics API. This allows for better user engagement (by mimicking the behavior of GIFs).</doc-alert>

<doc-alert type="warning">As mentionned earlier, TwicPics generates videos without sound. However, the `muted` attribute is still required for the browser to automatically play a video.</doc-alert>

### Browser codec compatibility

> As of March 8th, 2023.

| Codec        | Chrome | Safari | Firefox | Edge | Opera |
| ------------ | ------ | ------ | ------- | ---- | ----- |
| `h265` (mp4) | ❌     | ✅     | ❌      | ❌   | ❌    |
| `vp9` (WebM) | ✅     | ❌     | ✅      | ✅   | ✅    |
| `h264` (mp4) | ✅     | ✅     | ✅      | ✅   | ✅    |

---

## Handling LCP Videos

# Handling LCP Videos

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

The API is not suitable for hero videos with an LCP stake, as the equivalent of the `<picture>` tag does not yet exist for videos. As for TwicPics Native, it tends to generate too many variants when used to optimize hero videos, which are usually displayed in full width. This is partly due to the fact that the Script respects the defined [step](https://www.twicpics.com/docs/essentials/native#global-configuration).

We introduced the [data-twic-intrinsic](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic) attribute to solve all these problems.

The `data-twic-intrinsic` attribute can be used to specify the intrinsic dimensions of the original hero video:

- it prevents TwicPics Native from generating too many variants for better caching and better performance
- it prevents any form of upscaling — even if videos are not resized beyond their dimensions by default
- it allows using TwicPics Native for hero videos while perfectly optimizing the LCP metric in real-time

_Syntax_: `data-twic-intrinsic="<width>x<height>"`

```html
<!-- HTML source code -->
<div class="video-container">
  <video
    data-twic-src="media:video/skater.mp4"
    data-twic-intrinsic="1920x1080"
  ></video>
</div>
```

---

## Local development

# Local development

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

TwicPics requires original assets to be available via a public URL. This can be a limitation in the development phase as you work with local assets. This guide will walk you through the process of using TwicPics for your local files.

To do so we will:

1. Open a secure tunnel to your local files
2. Configure a TwicPics path mapping your local files

This requires an internet connection. To work offline, use the components [offline option](https://www.twicpics.com/docs/components/react#setup-options).

## Opening a tunnel using ngrok

[ngrok](https://ngrok.com/) is a command-line application that enables you to make a local port of your machine available online.

1. [Create a free ngrok account](https://ngrok.com/signup)
2. [Install the ngrok command-line interface](https://ngrok.com/docs/getting-started)
3. Verify your installation by running `ngrok --version`

After ngrok is installed, you can run `ngrok http <port>` to forward a local port of your machine. We will use this to make our local assets available publicly.

For example, if your development server is serving your web application on `http://localhost:3000`, you need to run `ngrok http 3000`.

> Change the port depending on the port of your development server.

ngrok will prompt something similar to the following:

```
Visit http://localhost:4040/ to inspect, replay, and modify your requests

Session Status                online
Account                       YourAccount (Plan: Free)
Version                       3.0.6
Region                        Europe (eu)
Latency                       11ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://a60d-2a01-e0a-20b-ff40-a138-2dd2-c9e9-a2f0.eu.ngrok.io -> http://localhost:3000
```

In this example, it means that `https://a60d-2a01-e0a-20b-ff40-a138-2dd2-c9e9-a2f0.eu.ngrok.io` (we’ll call it the **forwarding URL**) is mapping to `http://localhost:3000`.

You can navigate to your forwarding URL to make sure it’s working. You should see the same results as on your localhost.

<doc-alert type="info">
The <strong>forwarding URL</strong> will be different every time you run the ngrok command. So yours should be different from this example.
</doc-alert>

## Setting up a TwicPics path for local files

Now that ngrok is running, you will need to configure a new path in your [TwicPics dashboard](https://account.twicpics.com/dashboard).

1. Navigate to the relevant workspace and domain and click _Create Path_
2. Give your path a name, eg. `ngrok`
3. Fill in the _Source URL_ with the path to your images using the **forwarding URL**, e.g., `https://a60d-2a01-e0a-20b-ff40-a138-2dd2-c9e9-a2f0.eu.ngrok.io/images/`

And that’s it! TwicPics is now able to retrieve your local files. 🎉

If your path name is `ngrok` and your local image is at `localhost:3000/images/file.jpg`, you can access it with the following code:

```html
<!-- Using Twicpics components -->
<TwicImg src="ngrok/file.jpg" />

<!-- Or using the TwicPics Native -->
<img data-twic-src="image:ngrok/file.jpg" />
```

**Learn more about [paths configuration](https://www.twicpics.com/docs/essentials/path-configuration).**

---

## Multiple Environments

# Multiple Environments

Users on the **Business** tier or higher can create multiple workspaces, allowing to have multiple domains. This comes in handy when needing to switch between environments, say between your production and staging environment.

Here is an example of a configuration with two domains:

| domain              | path     | source images folder                        |
| ------------------- | -------- | ------------------------------------------- |
| `prod.twic.pics`    | `/`      | `https://www.my-company.com/assets/`        |
|                     | `/logo`  | `https://media.my-company.com/images/logo/` |
|                     | `/media` | `https://media.my-company.com/web/`         |
| `staging.twic.pics` | `/`      | `https://staging.my-company.com/assets/`    |
|                     | `/logo`  | `https://media.my-company.com/images/logo/` |
|                     | `/media` | `https://media.my-company.com/web/`         |

All you have to do now is reference the domain corresponding to the environment you are currently in (`prod.twic.pics` or `staging.twic.pics`) throughout your code base, which is usually as simple as setting a single variable and using it wherever you reference your TwicPics domain.

---

## Testing Placeholders

# Testing Placeholders

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

This section will guide you into using the [placeholders API](https://www.twicpics.com/docs/reference/placeholders) as a quality-control tool for your responsive designs.

## Implementing placeholders

Whenever you want the Script to handle a placeholder, simply set the `data-twic-src` attribute to `placeholder:auto`:

```html
<!-- with HTML attributes -->
<img data-twic-src="placeholder:auto" width="300" height="300" />

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

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 placeholders 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. You can alter this behavior. [Check the documentation](https://www.twicpics.com/docs/essentials/native#global-configuration).</doc-alert>

You can also use placeholders as backgrounds:

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

<div class="bg" data-twic-background="url(placeholder:auto)"></div>
```

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

<code-pen id="oNbdVXo" title="Placeholders by TwicPics (Basics)"></code-pen>

## Responsive Placeholders

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="placeholder:auto" />
  </figure>
</main>
```

Your placeholder 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.

<code-pen id="WNrMLYa" title="Placeholders by TwicPics (aspect ratio padding trick)"></code-pen>

## Placeholder API to the rescue

You might have noticed that all the examples so far made use of `placeholder:auto`. The term "auto" stands for "automatic sizing with default colors".

The complete syntax for placeholders is as follows: `placeholder:[<size>:]<color>`. For instance: `https://i.twic.pics/v1/placeholder:150x150:medium-violet-red`

The Script understands this syntax fully:

```html
<main>
  <figure class="img-16-9">
    <img data-twic-src="placeholder:deep-pink" />
  </figure>
</main>
```

Placeholders can also be used in production. For instance, using the same color for text and background generates a monochromatic placeholder: `https://i.twic.pics/v1/placeholder:ccc/ccc‍`. Even transparent placeholders are possible: `https://i.twic.pics/v1/placeholder:transparent‍`

The API offers many other features that you can find in [the dedicated section of the documentation](https://www.twicpics.com/docs/reference/placeholders).

Here is a more complete example you can toy with at [CodePen](https://codepen.io/twicpics/pen/QRmmrd):

<code-pen id="QRmmrd" title="Mockup Demo with Placeholders by TwicPics"></code-pen>

---


---

# Components

## Angular

# Angular

<illustration src="github/components/main/documentation/resources/angular-cover.png" width="1906" height="764" alt="TwicPics Angular Components"></illustration>

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

TwicPics Components are available in Angular **version 11 to 18**.

Discover our demonstrations and integration examples [in a standalone components based project](https://twicpics-angular-demo.netlify.app/home?utm_source=github&utm_campaign=components&utm_medium=organic).

For an example of integration into an NgModule-based project, please refer to [this repo](https://github.com/TwicPics/components-demo-angular/tree/ng-module-based-application).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components
# Or using npm
npm install @twicpics/components
```

## Setup

### Setting-up TwicPics Components into your `Angular` project

<doc-alert type="info">You will need a TwicPics domain to initialize the package. <a href="https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components" target="_blank">Create an account for free</a> to get your domain.</doc-alert>

Add the import part:

```ts
import { installTwicPics } from '@twicpics/components/angular18'
```

And the configuration part (see [Setup Options](#setup-options)):

```ts
installTwicPics({
  // domain is mandatory
  domain: 'https://<your-domain>.twic.pics',
})
```

into the main component of your `Angular` project.

#### app.component.ts

```ts
//here is an example of a `Angular` app.component.ts configured with TwicPics.
import { Component } from '@angular/core'
import { installTwicPics } from '@twicpics/components/angular18'
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrl: ''./app.component.css',
})
export class AppComponent {}

// TwicPics Components configuration
installTwicPics({
  domain: 'https://<your-domain>.twic.pics',
  anticipation: 0.5,
  breakpoints: {
    sm: 576,
  }
  step: 100,
})
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Components importation

TwicPics components for `Angular` come as an [Angular Module](https://angular.io/guide/architecture-modules).

Depending on the nature of your application, you'll need to import them either:

- directly into a [standalone component](https://angular.io/guide/standalone-components)
- into the application's **root module** (when using a [NgModule-based application](https://angular.io/guide/architecture-modules))

### Usage within a standalone component

```ts
// src/app/example/example.component.ts
import { Component } from '@angular/core';
import { TwicPicsComponentsModule } from '@twicpics/components/angular18';

@Component({
  // example is a standalone component
  standalone: true,
  selector: 'app-example',
  styleUrls: ['./example.component.scss'],
  templateUrl: './example.component.html',
  // TwicPics components are imported directly into you standalone component
  imports: [ TwicPicsComponentsModule ]
})
export class ExampleComponent {
  // logic
}
```

### Usage within NgModule-based application

```ts
// src/app/app.module.ts
import { NgModule } from '@angular/core'
import { AppComponent } from './app.component'
import { TwicPicsComponentsModule } from '@twicpics/components/angular14'
// other imports

@NgModule({
  declarations: [AppComponent],
  imports: [TwicPicsComponentsModule, ... other imported modules],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}
```

## Usage

`TwicImg`, `TwicPicture` and `TwicVideo` are available in the module scope into which you have imported `TwicPicsComponentsModule`.

Use them in your template files instead of `img`, `picture`, or `video` tags.

```html
<!-- component.html -->
<TwicImg src="path/to/your/image"></TwicImg>
<TwicPicture src="path/to/your/video"></TwicPicture>
<TwicVideo src="path/to/your/video"></TwicVideo>
```

### Basic usage

```html
<!-- component.html -->
<main>
  <TwicImg src="path/to/your/image"/>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src%2Fapp%2Ftwic-basic-grid%2Ftwic-basic-grid.component.html&initialpath=basic-grid)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src%2Fapp%2Ftwic-bulk-loading%2Ftwic-bulk-loading.component.html&initialpath=bulk-loading)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

`<your-component-within-app.module>.component.css`

```css
.landscape {
  --twic-ratio: calc(4/3);
}

.portrait {
  --twic-ratio: calc(3/4);
}

.square {
  --twic-ratio: calc(1);
}

.contain {
  --twic-mode: contain;
}

.cover {
  --twic-mode: cover;
}

.left {
  --twic-position: left;
}

.right {
  --twic-position: right;
}

.lg {
  width:300px;
}

.md {
  width:150px;
}

.sm {
  width: 100px;
}
```

```html
<!-- component.html -->
<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="contain left">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
  <div class="contain right">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="sm">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <!---
  Attributes take precedence over CSS.
  In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
  --->
  <div className="cover square">
    <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src%2Fapp%2Ftwic-style-driven%2Ftwic-style-driven.component.html&initialpath=style-driven)

### Lifecycle

For `TwicImg` and `TwicVideo` components, binding to `stateChangeEvent` gives access to the loading state of your image or video.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.html -->
<TwicImg
  src="path/to/your/image"
  (stateChangeEvent)="handleStateChange($event)"
></TwicImg>
```

#### Using standalone component

```ts
  // component.ts
  import { ChangeDetectorRef, Component } from "@angular/core";
  import { State, StateEvent, TwicPicsComponentsModule, TwicImgComponent } from "@twicpics/components/angular13";

  @Component({
    ...
    standalone: true,
    imports: [TwicPicsComponentsModule]
    ...
  })
  export class Component {

    state?: State;

    constructor(private changeDetector: ChangeDetectorRef) { }

    handleStateChange = (stateEvent: StateEvent) => {
      // Implement the logic here
      const { state, target } = stateEvent;
      const _target = target as TwicImgComponent;
      // eslint-disable-next-line no-console
      console.log( `TwicComponent emits a new state`, state );
      // eslint-disable-next-line no-console
      console.log( `TwicComponent source was`, _target.src );
      this.state = state;
      this.changeDetector.detectChanges();
    }

    // other logic
  }
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src/app/twic-state/twic-state.component.html&initialpath=state)

#### Using NgModule-based application

```ts
  // component.ts
  import { ChangeDetectorRef, Component } from "@angular/core";
  import { State, StateEvent, TwicImgComponent } from "@twicpics/components/angular13";

  export class Component {

  state?: State;

  constructor(private changeDetector: ChangeDetectorRef) { }

  handleStateChange = (stateEvent: StateEvent) => {
    // Implement the logic here
    const { state, target } = stateEvent;
    const _target = target as TwicImgComponent;
    // eslint-disable-next-line no-console
    console.log( `TwicComponent emits a new state`, state );
    // eslint-disable-next-line no-console
    console.log( `TwicComponent source was`, _target.src );
    this.state = state;
    this.changeDetector.detectChanges();
  }
```

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src/app/twic-zoom/twic-zoom.component.html&initialpath=zoom)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src/app/twic-refit/twic-refit.component.html&initialpath=refit)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

`<your-component-within-app.module>.component.css`

```css
.style-driven-responsive {
  --twic-ratio: calc(2 / 3);
  --twic-mode: cover;
  margin: auto;
}

@media (min-width: 640px) {
  .style-driven-responsive {
    --twic-ratio: calc(1);
  }
}

@media (min-width: 768px) {
  .style-driven-responsive {
    --twic-ratio: calc(4 / 3);
  }
}

@media (min-width: 1024px) {
  .style-driven-responsive {
    --twic-ratio: calc(16 / 9);
  }
}

@media (min-width: 1280px) {
  .style-driven-responsive {
    --twic-ratio: calc(1.85);
  }
}

@media (min-width: 1536px) {
  .style-driven-responsive {
    --twic-ratio: calc(21 / 9);
  }
}

```

```html
<!-- component.html -->
<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src%2Fapp%2Ftwic-art-direction%2Ftwic-art-direction.component.html&initialpath=art-direction)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

`styles.css`

```css
/* You are responsible for properly sizing the component. */
.hero-image {
  height:500px;
}

@media (min-width: 1024px) {
  .hero-image {
    height:300px;
    width:100%;
  }
}
```

`<your-page-or-component>.html`

```html
<TwicImg
  src="path/to/your/image"
  class="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-angular?file=src%2Fapp%2Ftwic-hero%2Ftwic-hero.component.html&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  (stateChangeEvent)="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChangeEvent` | An event emitter triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`EventEmitter<StateEvent>`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  (stateChangeEvent)="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChangeEvent` | An event emitter triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`EventEmitter<StateEvent>`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Anchor Type

Union type for all possible values on `anchor` property:

```ts
type Anchor = `bottom` | `bottom-left` | `bottom-right` | `center` | `left` | `top` | `top-left` | `top-right` | `right`;
```

#### Usage

To dynamically set the `anchor` property with the `TwicImg`, `TwicPicture` or `TwicVideo` component, you must declare a variable of type `Anchor`.

```ts
// component.ts
import { Anchor } from "@twicpics/components/angular14";

@Component({
  selector: ...,
  templateUrl: ...,
  styleUrls: ...,
})
export class YourComponent {
  yourAnchorVariable:Anchor = `top-left`;
}
```

```html
<!-- component.html -->
<TwicImg src="path/to/your/image" [anchor]="yourAnchorVariable"></TwicImg>
```

### Mode Type

Union type for all possible values on `mode` property:

```ts
type Mode = `contain` | `cover`;
```

#### Usage

To dynamically set the `mode` property with the `TwicImg`, `TwicPicture` or `TwicVideo` component, you must declare a variable of type `Mode`.

```ts
// component.ts
import { Mode } from "@twicpics/components/angular14";

@Component({
  selector: ...,
  templateUrl: ...,
  styleUrls: ...,
})
export class YourComponent {
  yourModeVariable:Mode = `contain`;
}
```

```html
<!-- component.html -->
<TwicImg src="path/to/your/image" [mode]="yourModeVariable"></TwicImg>
```

### Placeholder Type

Union type for all possible values on `placeholder` property:

```ts
type Placeholder = `maincolor` | `meancolor` | `none` | `preview`;
```

#### Usage

To dynamically set the `mode` property with the `TwicImg`, `TwicPicture` or `TwicVideo` component, you must declare a variable of type `Placeholder`.

```ts
  // component.ts
  import { Placeholder } from "@twicpics/components/angular14";

  @Component({
    selector: ...,
    templateUrl: ...,
    styleUrls: ...,
  })
  export class YourComponent {
    yourPlaceholderVariable:Placeholder = `none`;
}
```

```html
<!-- component.html -->
<TwicImg
  src="path/to/your/image" 
  [placeholder]="yourPlaceholderVariable">
</TwicImg>
```

### Loading State Values

Union type for all possible state values emitted through `@output` property `stateChangeEvent`:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type emitted by `@output` property `stateChangeEvent`:

```ts
export type StateEvent = {
  target: TwicImgComponent | TwicVideoComponent,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Flutter

# Flutter

<illustration src="github/components-flutter/main/resources/flutter-cover.png" width="1906" height="764" alt="TwicPics Flutter Widgets"></illustration>

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

`TwicPics Flutter Widget` is available as a [Flutter Package](https://pub.dev/packages/twicpics_components).

## Installation

Add the `twicpics_components` package to your `Flutter` project by running:

```bash
flutter pub add twicpics_components
```

## Setup

### Install TwicPics in your Flutter project

<doc-alert type="info">You will need a TwicPics domain to initialize the package. <a href="https://account.twicpics.com/signup" target="_blank">Create an account for free</a> to get your domain.</doc-alert>

```dart
// main.dart

import 'package:twicpics_components/twicpics_components.dart';

void main() {
  install(
    domain: "https://<your-domain>.twic.pics/",
  );
  runApp(...);
}
```

For an exhaustive list of options, see [Setup Options](#setup-options).

### Setup Options

| Option | Description | Type | Default |
| :- | :- | :- | :- |
| `cacheCleanOnStartUp` | Clears the cache when the application starts. | `boolean` | `false` |
| `cacheStalePeriod` | Defines the duration of validity of a cached asset. | `Duration` | `Duration( days: 7)` |
| `cacheMaxNrOfObjects` | Defines how large the cache is allowed to be. | `Integer` | `200` |
| `debug` | Activate logs from the cache manager. | `boolean` | `false` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration). Providing it is **mandatory**. | `String` | |
| `maxDPR` | [TwicPics](https://www.twicpics.com/) will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, [TwicPics](https://www.twicpics.com/) will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number`  | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step`   | To avoid requesting too may variants of the same image, [TwicPics](https://www.twicpics.com/) will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `50` |

## Usage

`TwicImg` and `TwicVideo` come as `Flutter Widgets` and are used as [such](https://docs.flutter.dev/ui/widgets-intro).

### Basic usage

```dart
// my_widget.dart

import 'package:twicpics_components/twicpics_components.dart';

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
    );
  }
}
```

### Bulk loading

When embedding `TwicImg` or `TwicVideo` in a lazily loading-compatible tree, it is recommended to disable lazy-loading feature:

```dart
// grid_sample.dart

class GridSample extends StatelessWidget {
  const GridSample({super.key});
  @override
  Widget build(BuildContext context) {
    return GridView.count(
      primary: false,
      crossAxisCount: 3,
      children: [
        TwicImg(
          src: 'path/to/my/image',
          eager: true,
        ),
        TwicVideo(
          src: 'path/to/my/video',
          eager: true,
        ),
        // ...
      ]
    );
}
```

### Choose your focus

You can control the crop function by using the `focus` property.

Read more about [focus](https://www.twicpics.com/docs/reference/transformations#focus).

#### Set the focus point to coordinates

```dart
// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: '30px40p', // this will set the focus point coordinates using relative lengths
    );
  }
}
```

```dart
// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: '345x678', // this will set the focus point coordinates using absolute lengths
    );
  }
}
```

#### Set the focus automagically

```dart
// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      focus: 'auto', // the focus point will be chosen automagically for you
    );
  }
}
```

<doc-alert type="warning">
Note that <code>auto</code> is not implemented for videos yet and is only available for <code>TwicImg</code>. 
</doc-alert>

### Working with ratio="none"

Allows to display both image or video with a __free height__ while respecting its __natural aspect-ratio__.

#### Hero image

An image that occupies all available space:

```dart
// my_widget.dart

import 'package:flutter/material.dart';
import 'package:twicpics_components/twicpics_components.dart';

class HeroSample extends StatelessWidget {
  const HeroSample({super.key});
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: double.infinity,
      child: TwicImg(
        src: 'path/to/my/image.jpg',
          ratio: 'none',
        ),
    );
  }
}
```

#### Hero video

An video that occupies all available space:

```dart
// my_widget.dart

import 'package:flutter/material.dart';
import 'package:twicpics_components/twicpics_components.dart';

class HeroSample extends StatelessWidget {
  const HeroSample({super.key});
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: double.infinity,
      child: TwicVideo(
        src: 'path/to/my/video.jpg',
          ratio: 'none',
        ),
    );
  }
}
```

#### Hero banner

You can specify the height of your image (or video) while respecting its __natural aspect-ratio__ and optimizing your Cumulative Layout Shift (CLS) metric.

```dart
// my_widget.dart

import 'package:flutter/material.dart';
import 'package:twicpics_components/twicpics_components.dart';

class HeroBanner extends StatelessWidget {
  const HeroBanner({super.key});
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: double.infinity,
      height: 200,
      child: TwicImg(
        src: 'path/to/my/image.jpg',
        ratio: 'none',
      ),
    );
  }
}
```

### Reframe your image

You can **reframe** your image on the **main subject(s)** it contains.

In **cover** `mode`, the resulting image will respect `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image will be cropped as close as possible to the main subject(s).

To activate automatic cropping, simply add the `refit` property to your widget call.

Read more about [refit](https://www.twicpics.com/docs/reference/transformations#refit).

```dart
// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      anchor: TwicPosition.right, // will align main subject(s) with the right border
      src: 'path/to/my/image',
      mode: TwicMode.cover, // will maximize the area occupied by the main subject(s) in a squared area
      refit: '10p', // will add a 10% padding around the main subject(s)
    );
  }
}
```

```dart
// my_widget.dart

class MyWidget extends StatelessWidget {
  const MyWidget({super.key});
  @override
  Widget build(BuildContext context) {
    return TwicImg(
      src: 'path/to/my/image',
      mode: TwicMode.contain, // will crop the image as close as possible to main subject(s)
      refit: true, // default refit without any padding
    );
  }
}
```

<doc-alert type="warning">
Note that <code>refit</code> is not implemented for videos yet and is only available for <code>TwicImg</code>.
</doc-alert>

### Working with Row Widget

When using [Row Widget](https://api.flutter.dev/flutter/widgets/Row-class.html) you have to **constrain available width** for `TwicImg` as in:

```dart
import 'package:flutter/material.dart';
import 'package:twicpics_components/twicpics_components.dart';

class RowSample extends StatelessWidget {
  const RowSample({super.key});
  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        SizedBox(
          width: 100, //fixed width
          child: TwicImg(
            src:'path/to/my/image',
          ),
        ),
        Expanded( // makes child fills the available space
          child: TwicVideo(
            src:'path/to/my/video',
          ),
        ),
      ],
    );
  }
}
```

## Widget Properties

### TwicImg

```dart
TwicImg( 
  { 
      Key? key,
      TwicPosition? anchor,
      bool? eager,
      String? focus,
      String? intrinsic,
      TwicMode? mode,
      TwicPlaceholder? placeholder,
      TwicPosition? position,
      String? preTransform,
      <String? | double?> ratio,
      <String? | bool?> refit,
      required String src,
      int? step,
      Duration? transitionDuration,
  } 
)
```

| Attribute | Description | Type | Default |
| :- | :- | :- | :- |
| `key` | Keeps widget state when parent tree rebuilds. | [Key](https://api.flutter.dev/flutter/widgets/Widget/key.html) | |
| `anchor` | Positions the image in both `TwicMode.contain` and `TwicMode.cover` mode. `position` and `focus` take precedence in `TwicMode.contain` and `TwicMode.cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. | [TwicPosition](#twicposition-enum) | |
| `eager` | Load the image as soon as the widget is mounted. This effectively means disabling lazy loading for this image. Recommended when `TwicImg` is placed within a parent that natively handles lazy-loading. | `boolean` | `false` |
| `focus` | Sets the focus point in `TwicMode.cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning ([TwicPosition](#twicposition-enum) values), use `anchor` instead.  | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic). `String`  | |
| `mode` | Determines if the image fills the area and is cropped accordingly (`TwicMode.cover`) or if the image will sit inside the area with no cropping (`TwicMode.contain`). | [TwicMode](#twicmode-enum) | `TwicMode.cover` |
| `placeholder` | Displays a low quality version before the final image is actually loaded. | [TwicPlaceholder](#twicplaceholder-enum) | `TwicPlaceholder.preview` |
 `position` | Positions the image in `TwicMode.contain` mode. `position` takes precedence over `anchor` when both are provided. Only use this property if you need precise positionning: if you only need border-based positionning ([TwicPosition](#twicposition-enum) values), use `anchor` instead. | [TwicPosition](#twicposition-enum) | `TwicPosition.center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the Flutter following the parent size definitions. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `src` | Mandatory path to the image. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `int` |  |
| `transitionDuration` | Duration of the transition effect between placeholder and the final image. | `Duration` | `Duration( milliseconds: 400 )` |

### TwicVideo

```dart
TwicVideo( 
  { 
      Key? key,
      TwicPosition? anchor,
      <String? | double?> duration,
      bool? eager,
      String? focus,
      <String? | double?> from,
      String? intrinsic,
      TwicMode? mode,
      <String? | double?> posterFrom,
      TwicPlaceholder? placeholder,
      TwicPosition? position,
      String? preTransform,
      <String? | double?> posterFrom,
      <String? | double?> ratio,
      required String src,
      <String? | double?> to,
      int? step,
      Duration? transitionDuration,
  } 
)
```

| Attribute | Description | Type | Default |
| :- | :- | :- | :- |
| `key` | Keeps widget state when parent tree rebuilds. | [Key](https://api.flutter.dev/flutter/widgets/Widget/key.html) | |
| `anchor` | Positions the video in both `TwicMode.contain` and `TwicMode.cover` mode. `position` and `focus` take precedence in `TwicMode.contain` and `TwicMode.cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. | [TwicPosition](#twicposition-enum) | |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the widget is mounted. This effectively means disabling lazy loading for this video. Recommended when `TwicVideo` is placed within a parent that natively handles lazy-loading. | `boolean` | `false` |
| `focus` | Sets the focus point in `TwicMode.cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point: if you only need border-based positionning ([TwicPosition](#twicposition-enum) values), use `anchor` instead.  | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic). `String`  | |
| `mode` | Determines if the video fills the area and is cropped accordingly (`TwicMode.cover`) or if the video will sit inside the area with no cropping (`TwicMode.contain`). | [TwicMode](#twicmode-enum) | `TwicMode.cover` |
| `placeholder` | Displays a low quality version before the final video is actually loaded. | [TwicPlaceholder](#twicplaceholder-enum) | `TwicPlaceholder.preview` |
 `position` | Positions the video in `TwicMode.contain` mode. `position` takes precedence over `anchor` when both are provided. Only use this property if you need precise positionning: if you only need border-based positionning ([TwicPosition](#twicposition-enum) values), use `anchor` instead. | [TwicPosition](#twicposition-enum) | `TwicPosition.center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=20px30p/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the Flutter following the parent size definitions. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `src` | Mandatory path to the video. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `int` |  |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
| `transitionDuration` | Duration of the transition effect between placeholder and the video or its poster. | `Duration` | `Duration( milliseconds: 400 )` |

### TwicMode enum

Defines how assets should be resized to fit its container.

| Value | Description |
| :- | :- |
| `contain` | resize asset so that it completely fits inside the target area while conserving the original aspect ratio. |
| `cover` | resize asset so that it completely fills the target area while conserving the original aspect ratio. |

### TwicPosition enum

Defines a position within the parent container.

| Value | Description |
| :- | :- |
| `bottom` | The center point along the bottom edge. |
| `bottomLeft` | The bottom left corner. |
| `bottomRight` | The bottom right corner. |
| `center` | The center point, both horizontally and vertically. |
| `left` | The center point along the left edge. |
| `right` | The center point along the right edge. |
| `top` | The center point along the top edge. |
| `topLeft` | The top left corner. |
| `topRight` | The top right corner. |

### TwicPlaceholder enum

Defines placeholder characteristics.

| Value | Description |
| :- | :- |
| `preview` | displays a **blurry preview** of requested asset. |
| `maincolor` | fills container with a solid color containing the **most important** color in the requested asset. |
| `meancolor` | fills container with a solid color containing the **mean color** in the requested asset. |
| `none` | displays an empty container. |

## Feedback and support

TwicPics Flutter Widgets are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components-flutter/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Gatsby

# Gatsby

<illustration src="github/components/main/documentation/resources/gatsby-cover.png" width="1906" height="764" alt="TwicPics Gatsby Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-gatsby-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components
# Or using npm
npm install @twicpics/components
```

## Setup

### Setting up TwicPics Components in your `Gatsby` project

TwicPics components for `Gatsby` come as a `Gatsby Plugin` and are configured as [such](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/using-a-plugin-in-your-site/).

<doc-alert type="info">You will need a TwicPics domain to initialize the package. <a href="https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components" target="_blank">Create an account for free</a> to get your domain.</doc-alert>

#### `gatsby-config.js`

Add `@twicpics/components/gatsby` to the plugins section with your TwicPics configuration as plugin options:

```json
{
  "resolve": "@twicpics/components/gatsby",
  "options": {
    "twicpics": {
      "domain": "https://<your-domain>.twic.pics",
    },
  },
}
```

```js
// here is an example of a `gatsby-config.js` configured with TwicPics.
module.exports = {
  "siteMetadata": {
    "title": "twicpics x gatsby",
    "siteUrl": "https://www.yourdomain.tld",
  },
  "plugins": [
      {
        "resolve": "@twicpics/components/gatsby",
        "options": {
          "twicpics": {
            "domain": "https://<your-domain>.twic.pics"
          },
        },
      },
  ],
};
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part:

```js
// this component will be used in instead of an img element.
// nb : Gatsby uses react components
import { TwicImg } from "@twicpics/components/react";

// this component will be used in instead of a `picture` element.
// nb : Gatsby uses react components
import { TwicPicture } from "@twicpics/components/react";

// this component will be used in instead of a video element.
// nb : Gatsby uses react components
import { TwicVideo } from "@twicpics/components/react";
```

then, use `<TwicImg>`, `<TwicPicture>` or `<TwicVideo>` instead of standard tags `<img>`, `<picture>` or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

> TwicPics Components can also be used in `js`, `jsx`, `ts`, `tsx` files.

```js
// component.js
import * as React from 'react';
import { TwicImg } from "@twicpics/components/react";

const YourTemplate = () => (
  <TwicImg src="path/to/your/image"/>
);

export default YourTemplate;
```

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

### Lifecycle

For the `TwicImg` and the `TwicVideo` components, passing a callback function to `onStateChange` gives access to your image or video loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```js
  // component.jsx
  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

<doc-alert type="info">When using `onStateChange` in a <b>Server Components module graph</b>, your component must be decorated with  <a href="https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive" target="_blank">use client directive</a>, as in:</doc-alert>

```js
  'use client'
  
  // your imports

  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

`styles.css`

```css
.landscape {
  --twic-ratio: calc(4/3);
}

.portrait {
  --twic-ratio: calc(3/4);
}

.square {
  --twic-ratio: calc(1);
}

.contain {
    --twic-mode: contain;
}

.cover {
  --twic-mode: cover;
}

.left {
  --twic-position: left;
}

.right {
  --twic-position: right;
}

.lg {
  width:300px;
}

.md {
  width:150px;
}

.sm {
  width: 100px;
}
```

```html
<!-- component.jsx -->
<div className="landscape">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="square">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="portrait">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="contain left">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
<div className="contain right">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
<!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
<div className="cover square">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
```

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

`styles.css`

```css
.style-driven {
  --twic-ratio: 1.9;
}

@media ( min-width: 640px ) {
  .style-driven {
    --twic-mode: contain;
  }
}

@media ( min-width: 768px ) {
  .style-driven {
    --twic-mode: cover;
    --twic-ratio: calc( 4/3 );
  }
}

@media (min-width: 1024px) {
  .style-driven {
    --twic-ratio: calc( 16/9 );
  }
}

@media ( min-width: 1280px ) {
  .style-driven {
    --twic-ratio: calc( 21/9 );
  }
}

@media ( min-width: 1536px ) {
  .style-driven {
    --twic-ratio: calc( 36/9 );
  }
}
```

```html
<!-- component.html -->
<TwicImg
className="style-driven"
src="path/to/your/image"
></TwicImg>
```

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

`styles.css`

```css
/* You are responsible for properly sizing the component. */
.hero-image {
  height:500px;
}

@media (min-width: 1024px) {
  .hero-image {
    height:300px;
    width:100%;
  }
}
```

```html
<!-- component.jsx -->
<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  onStateChange="<function>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  sizes="<String>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabIndex` | Specifies the tab order of the video. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `onStateChange` function:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Next

# Next.js

<illustration src="github/components/main/documentation/resources/nextjs-cover.png" width="1906" height="764" alt="TwicPics Next Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-next-demo.netlify.app/).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components
# Or using npm
npm install @twicpics/components
```

## Setup

If you only want to use the **Next.js loader**, skip to [Next.js Image Loader](#nextjs-image-loader).

### Install TwicPics In Your Next.js Project

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

Configuration of `TwicPics Components` depends on your application's setup, whether you are using [Next Pages Router](#using-next-pages-router) or [Next App Router](#using-next-app-router-next-13).

#### Using Next Pages Router

```tsx
// pages/_app.tsx
...
import { TwicInstall } from "@twicpics/components/react";
import "@twicpics/components/style.css";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      { /* TwicPics Components configuration (see TwicInstall) */ }
      <TwicInstall
        // domain is mandatory
        domain='https://demo.twic.pics'
      />
      <Component {...pageProps} />
    </>
  );
}
```

#### Using Next App Router (Next 13+)

```tsx
// app/layout.tsx
import { TwicInstall } from "@twicpics/components/react";
import "@twicpics/components/style.css";

export default function RootLayout( { children }: {
  children: React.ReactNode
} ) {
  return (
    <html lang="en">
      { /* TwicPics Components configuration (see TwicInstall) */ }
      <TwicInstall
        // domain is mandatory
        domain="https://<your-domain>.twic.pics"
      />
      <body>{children}</body>
    </html>
  );
}
```

### TwicInstall

This component configures `TwicPics Components` and must be placed in your project's entry point file.

```html
<TwicInstall
  domain="<String>"
  anticipation="<Number>"
  class="<String>"
  env="<debug|offline|production>"
  handleShadowDom="<boolean>"
  maxDPR="<Number>"
  path="<String>"
  step="<integer>"
/>
```

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

### Basic Usage

```tsx
// MyComponent.tsx

import { TwicImg } from "@twicpics/components/react";

const YourTemplate = () => (
  <TwicImg src="path/to/your/image"/>
);

export default YourTemplate;
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%2Fbasic-grid%2Findex.jsx&initialpath=basic-grid)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [TwicInstall](#twicinstall).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#twicinstall).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages/bulk-loading/index.jsx&initialpath=bulk-loading)

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%zoom%2Findex.jsx&initialpath=zoom)

### Lifecycle

For the `TwicImg` and the `TwicVideo` components, passing a callback function to `onStateChange` gives access to your image or video loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```js
  // component.jsx
  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

<doc-alert type="info">When using `onStateChange` in a <b>Server Components module graph</b>, your component must be decorated with  <a href="https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive" target="_blank">use client directive</a>, as in:</doc-alert>

```js
  'use client'
  
  // your imports

  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%2Fstate%2Findex.jsx&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%2Frefit%2Findex.jsx&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

#### CSSS

```css
.landscape {
  --twic-ratio: calc(4/3);
}

.portrait {
  --twic-ratio: calc(3/4);
}

.square {
  --twic-ratio: calc(1);
}

.contain {
  --twic-mode: contain;
}

.cover {
  --twic-mode: cover;
}

.left {
  --twic-position: left;
}

.right {
  --twic-position: right;
}

.lg {
  width:300px;
}

.md {
  width:150px;
}

.sm {
  width: 100px;
}
```

#### Template

```html
<div className="landscape">
  <TwicImg src="path/to/your/image"/>
</div>
<div className="square">
  <TwicImg src="path/to/your/image"/>
</div>
<div className="portrait">
  <TwicImg src="path/to/your/image"/>
</div>
<div className="contain left">
  <TwicImg src="path/to/your/image" ratio="16/9"/>
</div>
<div className="contain right">
  <TwicImg src="path/to/your/image" ratio="16/9"/>
</div>
<!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
<div className="cover square">
  <TwicImg src="path/to/your/image" ratio="16/9"/>
</div>
```

#### Demo

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages/style-driven/index.jsx&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```css
/* styles.css */

.style-driven {
  --twic-ratio: 1.9;
}

@media ( min-width: 640px ) {
  .style-driven {
    --twic-mode: contain;
  }
}

@media ( min-width: 768px ) {
  .style-driven {
    --twic-mode: cover;
    --twic-ratio: calc( 4/3 );
  }
}

@media (min-width: 1024px) {
  .style-driven {
    --twic-ratio: calc( 16/9 );
  }
}

@media ( min-width: 1280px ) {
  .style-driven {
    --twic-ratio: calc( 21/9 );
  }
}

@media ( min-width: 1536px ) {
  .style-driven {
    --twic-ratio: calc( 36/9 );
  }
}
```

Now, your template can feature a single component that follows your CSS directives and behaves responsively.

```jsx
// MyComponent.jsx

import 'style.css'

export default function() {
  return (
    <TwicImg
      className="style-driven"
      src="path/to/your/image"
    />
  )
}
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%2Fart-directions%2Findex.jsx&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```css
/* style.css */

.hero-image {
  height:500px;
}

@media (min-width: 1024px) {
  .hero-image {
    height:300px;
    width:100%;
  }
}
```

```jsx
// MyComponent.jsx

<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
/>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-next?file=pages%2Fhero%2Findex.jsx&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  onStateChange="<function>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#twicinstall) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  sizes="<String>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#twicinstall) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabIndex` | Specifies the tab order of the video. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `onStateChange` function:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [TwicInstall](#twicinstall).

## Next.js Image Loader

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

If it does not exist, create a `.env` file at the root of your project.

Set the `NEXT_PUBLIC_TWICPICS_DOMAIN` environment variable to your own [Twicpics domain](https://www.twicpics.com/docs/essentials/domain-configuration):

```bash
NEXT_PUBLIC_TWICPICS_DOMAIN="https://<your-domain>.twic.pics/"
```

### Basic Usage

The example below shows how to use the TwicPics loader:

```jsx
// MyComponent.jsx

import Image from 'next/image'
import { twicpicsLoader } from "@twicpics/components/next";

const MyImage = (props) => {
  return (
    <Image
      loader={twicpicsLoader}
      src="image.jpg"
      alt="Image alt description"
      width={500}
      height={500}
    />
  )
}
```

Please note that this will stretch the image to fit the specified size, which might not match the desired aspect ratio.

For more straightforward aspect ratio management, consider using the `<TwicImg>` component (see [Setup](#setup)). This will also give you access to all [TwicPics features](https://www.twicpics.com/docs/reference/transformations) like smart-cropping, automatic next-gen formats, and more.

### Using Placeholders

> This is only supported from Next.js 13.

The Next Image component allows to implement [low quality image placeholders](https://www.twicpics.com/docs/guides/image-best-practices#lqip--blurry-image-placeholder) by setting the `placeholder` prop to `blur`.

When doing so, we need to set the `blurDataURL` prop. This prop expects the URL of a Base64-encoded image. TwicPics provides a `twicpicsPlaceholder` helper that returns such URL.

```jsx
import Image from 'next/image'
import { twicpicsLoader, twicpicsPlaceholder } from "@twicpics/components/next";

// In this example, we're generating the placeholder URL on server-side
export async function getServerSideProps() {
  const data = {
    src: `image.jpg`,
  };
  datas.blurDataURL = await twicpicsPlaceholder(data.src);
  return {
    props: {
      data,
    },
  };
}

const MyImage = ({ data }) => {
  return (
    <Image
      loader={twicpicsLoader}
      src={data.src}
      placeholder="blur"
      blurDataURL={data.blurDataURL}
      alt="Image alt description"
    />
  )
}
```

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Nuxt 2

# Nuxt 2

<illustration src="github/components/main/documentation/resources/nuxt-cover.png" width="1906" height="764" alt="TwicPics Nuxt Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-nuxt2-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

### Setting up TwicPics Components in your `Nuxt2` project

TwicPics components for `Nuxt2` come as a `Nuxt2 Module` and are configured as [such](https://nuxtjs.org/docs/directory-structure/modules).

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

#### `nuxt.config.js`

Add `@twicpics/components/nuxt2` to the modules section

With your twicpics configuration

```js
export default {
  ...
  "modules": [
    [
      `@twicpics/components/nuxt2`,
      {
        "domain": `https://<your-domain>.twic.pics`,
      },
    ],
  ],
  ...
};
```

Or a separate section twicpics for component configuration:

```js
export default {
  ...
  "modules": [ `@twicpics/components/nuxt2` ],
  ...
  "twicpics": {
      "domain": `https://<your-domain>.twic.pics`,
  },
};
```

```js
// here is an example of a `nuxt.config.js` configured with TwicPics.
export default {
  head: {
    title: "TwicPics x Nuxt2",
  },
  modules: ["@twicpics/components/nuxt2"],
  twicpics: {
    "https://<your-domain>.twic.pics"
  },
};

```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

`TwicImg`, `TwicPicture` and `TwicVideo` are available in your templates as long as you have [configured the TwicPics Nuxt2 Module](#setup).

Just use them in your template files in instead of `img`, `picture` or `video` tags (see [Components Properties](#components-properties)).

```html
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

### Basic usage

```html
<!-- component.vue -->
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages%2Fbasic-grid.vue&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages%2Fbulk-loading.vue&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages/zoom.vue&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, passing a callback function to the `stateChange` emitter gives access to your image's or video's loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg
        src="path/to/your/image"
        @stateChange="handleStateChange"
      />
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
  data() {
    state:undefined
  },
  methods: {
    handleStateChange( stateEvent ) {
      // Implement the logic here
      const { state } = stateEvent;
      this.state = state;
      console.log( `TwicComponent emits a new state`, this.state );
    }
  }
};
</script>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages/state.vue&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages/refit.vue&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.vue -->
<template>
  <main>
    <div class="twic-item landscape">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item square">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item portrait">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item contain left">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item contain right">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item lg">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item md">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item sm">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
    <div class="cover square">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.landscape {
  --twic-ratio: calc(4 / 3);
}
.portrait {
  --twic-ratio: calc(3 / 4);
}
.square {
  --twic-ratio: calc(1);
}

.lg {
  width: 300px;
}

.md {
  width: 150px;
}

.sm {
  width: 100px;
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages%2Fstyle-driven.vue&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.style-driven-responsive {
  --twic-ratio: calc(2 / 3);
  --twic-mode: cover;
  margin: auto;
}

@media (min-width: 640px) {
  .style-driven-responsive {
    --twic-ratio: calc(1);
  }
}

@media (min-width: 768px) {
  .style-driven-responsive {
    --twic-ratio: calc(4 / 3);
  }
}

@media (min-width: 1024px) {
  .style-driven-responsive {
    --twic-ratio: calc(16 / 9);
  }
}

@media (min-width: 1280px) {
  .style-driven-responsive {
    --twic-ratio: calc(1.85);
  }
}

@media (min-width: 1536px) {
  .style-driven-responsive {
    --twic-ratio: calc(21 / 9);
  }
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages%2Fart-directions.vue&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

`<your-page-or-component>.vue`

```html
<template>
  <TwicImg
    src="path/to/your/image"
    class="hero-image"
    ratio="none"
 ></TwicImg>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt2?file=pages/hero.vue&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `stateChange` emitter:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Nuxt 3

# Nuxt 3

<illustration src="github/components/main/documentation/resources/nuxt-cover.png" width="1906" height="764" alt="TwicPics Nuxt Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-nuxt3-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

### Setting up TwicPics Components in your `Nuxt3` project

TwicPics components for `Nuxt3` come as an `Nuxt3 Module` and are configured as [such](https://nuxt.com/docs/guide/directory-structure/modules).

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

#### `nuxt.config.ts`

Add `@twicpics/components/nuxt3` to the modules section

With your twicpics configuration

```ts
export default defineNuxtConfig( {
    "modules": [ 
        `@twicpics/components/nuxt3`
    ],
    "twicpics": {
        "domain": `https://<your-domain>.twic.pics`,
    },
} );
```

```ts
// here is an example of a `nuxt.config.ts` configured with TwicPics.
export default defineNuxtConfig( {
    "modules":[
        `@twicpics/components/nuxt3`
    ] ,
    "twicpics": {
        "domain": `https://<your-domain>.twic.pics`,
        "anticipation": 0.5,
        "step": 50,
    },
} );

```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

`TwicImg`, `TwicPicture` and `TwicVideo`  are available in your templates as long as you have [configured the TwicPics Nuxt3 Module](#setup).

Just use them in your template files in instead of `img`, `picture` or `video` tags (see [Components Properties](#components-properties)).

```html
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

### Basic usage

```html
<!-- component.vue -->
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fbasic-grid.vue&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fbulk-loading.vue&initialpath=bulk-loading)

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fzoom.vue&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, passing a callback function to the `stateChange` emitter gives access to your image's or video's loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg
        src="path/to/your/image"
        @stateChange="handleStateChange"
      />
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
  data() {
    state:undefined
  },
  methods: {
    handleStateChange( stateEvent ) {
      // Implement the logic here
      const { state } = stateEvent;
      this.state = state;
      console.log( `TwicComponent emits a new state`, this.state );
    }
  }
};
</script>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fstate.vue&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Frefit.vue&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.vue -->
<template>
  <main>
    <div class="twic-item landscape">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item square">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item portrait">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item contain left">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item contain right">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item lg">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item md">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item sm">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
    <div class="cover square">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.landscape {
  --twic-ratio: calc(4 / 3);
}
.portrait {
  --twic-ratio: calc(3 / 4);
}
.square {
  --twic-ratio: calc(1);
}

.lg {
  width: 300px;
}

.md {
  width: 150px;
}

.sm {
  width: 100px;
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fstyle-driven.vue&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.style-driven-responsive {
  --twic-ratio: calc(2 / 3);
  --twic-mode: cover;
  margin: auto;
}

@media (min-width: 640px) {
  .style-driven-responsive {
    --twic-ratio: calc(1);
  }
}

@media (min-width: 768px) {
  .style-driven-responsive {
    --twic-ratio: calc(4 / 3);
  }
}

@media (min-width: 1024px) {
  .style-driven-responsive {
    --twic-ratio: calc(16 / 9);
  }
}

@media (min-width: 1280px) {
  .style-driven-responsive {
    --twic-ratio: calc(1.85);
  }
}

@media (min-width: 1536px) {
  .style-driven-responsive {
    --twic-ratio: calc(21 / 9);
  }
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fart-directions.vue&initialpath=art-directions)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.vue -->  
<template>
  <TwicImg
    src="path/to/your/image"
    class="hero-image"
    ratio="none"
  ></TwicImg>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-nuxt3?file=pages%2Fhero.vue&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `stateChange` emitter:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## React

# React

<illustration src="github/components/main/documentation/resources/react-cover.png" width="1906" height="764" alt="TwicPics React Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-react-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `React` project

While we recommend going the `ES module` route and use `import` statements, [TwicPics Components](https://www.npmjs.com/package/@twicpics/components) is also backward compatible with `CommonJS` and `require` statements.

Add the import part:

```jsx
// import TwicPics react components
import { installTwicpics } from "@twicpics/components/react";
// import TwicPics components css
import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```jsx
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );
```

In the entry point file your `React` project.

#### index.jsx (React 16+)

```jsx
// Here is an example of a `React 16+` app startup configured with TwicPics.
import React from "react";
import ReactDOM from "react-dom";
import Root from "./root.jsx";

// TwicPics Components importation
import { installTwicpics } from "@twicpics/components/react";
import "@twicpics/components/style.css";

// TwicPics Components configuration (see Setup Options)
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );

ReactDOM.render(
  <React.StrictMode>
    <Root />
  </React.StrictMode>,
  document.getElementById( "root" )
);
```

##### index.jsx (React 18+)

```jsx
// Here is an example of a `React 18+` app startup configured with TwicPics.
import React from "react";
import { createRoot } from 'react-dom/client';
import Root from "./root.jsx";

// TwicPics Components importation
import { installTwicpics } from "@twicpics/components/react";
import "@twicpics/components/style.css";

// TwicPics Components configuration (see Setup Options)
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );

const container = document.getElementById('root');
const root = createRoot(container); 

root.render(
      <Root />
);

```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part:

```jsx
// this component will be used in instead of an img element.
import { TwicImg } from "@twicpics/components/react";

// this component will be used in instead of a `picture` element.
import { TwicPicture } from "@twicpics/components/react";

// this component will be used in instead of an video element.
import { TwicVideo } from "@twicpics/components/react";
```

then, use `<TwicImg>`, `TwicPicture` or `<TwicVideo>` instead of standard tags `<img>`, `<picture>` or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

> TwicPics Components can also be used in `js`, `jsx`, `ts`, `tsx` files.

```jsx
// component.jsx
import React from "react";
import { TwicImg } from "@twicpics/components/react";

const YourTemplate = () => (
  <TwicImg src="path/to/your/image"/>
);

export default YourTemplate;
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%2FtwicBasicGrid%2Findex.jsx&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src/lib/twicBulkLoading/index.jsx&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%twicZoom%2Findex.jsx&initialpath=zoom)

### Lifecycle

For the `TwicImg` and the `TwicVideo` components, passing a callback function to `onStateChange` gives access to your image or video loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```js
  // component.jsx
  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

<doc-alert type="info">When using `onStateChange` in a <b>Server Components module graph</b>, your component must be decorated with  <a href="https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive" target="_blank">use client directive</a>, as in:</doc-alert>

```js
  'use client'
  
  // your imports

  const [ state, setState ] = useState( undefined );
  
  const handleStateChange = ( stateEvent ) => {
    // Implement the logic here
    const { state } = stateEvent;
    console.log( `TwicComponent emits a new state`, state );
    setState( state );
  }

  return (
    <TwicImg
      onStateChange={handleStateChange}
      src="path/to/your/image"
    />
  )
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%2FtwicState%2Findex.jsx&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%2FtwicRefit%2Findex.jsx&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

`styles.css`

```css
.landscape {
  --twic-ratio: calc(4/3);
}

.portrait {
  --twic-ratio: calc(3/4);
}

.square {
  --twic-ratio: calc(1);
}

.contain {
  --twic-mode: contain;
}

.cover {
  --twic-mode: cover;
}

.left {
  --twic-position: left;
}

.right {
  --twic-position: right;
}

.lg {
  width:300px;
}

.md {
  width:150px;
}

.sm {
  width: 100px;
}
```

```html
<!-- component.jsx -->
<div className="landscape">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="square">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="portrait">
  <TwicImg src=path/to/your/image></TwicImg>
</div>
<div className="contain left">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
<div className="contain right">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
<!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
<div className="cover square">
  <TwicImg src=path/to/your/image ratio="16/9"></TwicImg>
</div>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%2FtwicStyleDriven%2Findex.jsx&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

`styles.css`

```css
.style-driven {
  --twic-ratio: 1.9;
}

@media ( min-width: 640px ) {
  .style-driven {
    --twic-mode: contain;
  }
}

@media ( min-width: 768px ) {
  .style-driven {
    --twic-mode: cover;
    --twic-ratio: calc( 4/3 );
  }
}

@media (min-width: 1024px) {
  .style-driven {
    --twic-ratio: calc( 16/9 );
  }
}

@media ( min-width: 1280px ) {
  .style-driven {
    --twic-ratio: calc( 21/9 );
  }
}

@media ( min-width: 1536px ) {
  .style-driven {
    --twic-ratio: calc( 36/9 );
  }
}
```

```html
<!-- component.jsx -->
<TwicImg
  className="style-driven"
  src="path/to/your/image"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src/lib/twicArtDirections/index.jsx&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

`styles.css`

```css
/* You are responsible for properly sizing the component. */
.hero-image {
  height:500px;
}

@media (min-width: 1024px) {
  .hero-image {
    height:300px;
    width:100%;
  }
}
```

```html
<!-- component.jsx -->
<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-react?file=src%2Flib%2FtwicHero%2Findex.jsx&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  onStateChange="<function>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossOrigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<React.AriaRole>"
  sizes="<String>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabIndex` | Specifies the tab order of the image. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossOrigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  role="<React.AriaRole>"
  step="<integer>"
  style="<React.CSSProperties>"
  tabIndex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `onStateChange` | A callback function triggered each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `React.AriaRole` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `React.CSSProperties` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabIndex` | Specifies the tab order of the video. See [`global attribute tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `onStateChange` function:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## React Native

# React Native

<illustration src="github/components/main/documentation/resources/react-cover.png" width="1906" height="764" alt="TwicPics React Components"></illustration>

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

## Platform Compatibility

| Android | iOS | Web |
| :-: | :-: | :-: |
| [x] | [x] | [x] |

## Installation

### Installing TwicPics Components

Add the `@twicpics/components` package to your React Native project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

If you plan to use **image caching** or `TwicVideo`, you will also need to install additional [Expo Modules](#installing-expo-modules). If not, proceed directly to [setup](#setup) section.

### Installing Expo modules

The installation process for additional **Expo modules** depends on your project's origin, whether [Expo Go](https://reactnative.dev/docs/environment-setup?guide=quickstart&package-manager=yarn) or [React Native CLI](https://reactnative.dev/docs/environment-setup?guide=native&package-manager=yarn).

#### For React Native Expo Go projects

Since `Expo` is already installed, add the required dependencies as follows, depending on your needs:

```bash
# Expo AV installation (required for TwicVideo component)

## Using yarn
yarn add expo-av

## Or using npm
npm install expo-av
```

```bash
# Expo Image installation (required for image caching)

## Using yarn
yarn add expo-image

## Or using npm
npm install expo-image
```

Once completed, proceed to [setup](#setup) section.

#### For React Native CLI projects

First, install and configure the `Expo` package.

```bash
npx install-expo-modules@latest
```

**Note:** If the command fails, please refer to [Expo Modules documentation](https://docs.expo.dev/bare/installing-expo-modules/).

After `Expo` package is installed and configured, add the required dependencies as follows, depending on your needs:

```bash
# Expo AV installation (required for TwicVideo component)

## Using yarn
yarn add expo-av

## Or using npm
npm install expo-av
```

```bash
# Expo Image installation (required for image caching)

## Using yarn
yarn add expo-image

## Or using npm
npm install expo-image
```

For **iOS** targeting, reinstall the project's `CocoaPods`:

```bash
npx pod-install
```

## Setup

### Setting-up TwicPics Components in your React Native project

<doc-alert type="info">You will need a TwicPics domain to initialize the package. <a href="https://account.twicpics.com/signup" target="_blank">Create an account for free</a> to get your domain.</doc-alert>

```js
// App.js

import { installTwicPics } from '@twicpics/components/react-native';

installTwicPics({
  "domain": `https://<your-domain>.twic.pics/`,
});

export default function App() {
  return (
    // your app code
  )
}
```

For an exhaustive list of options, see [Setup Options](#setup-options).

### Setup Options

| Option   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Type      | Default        |
| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------- |
| `anticipation` | [TwicPics](https://www.twicpics.com/) will lazy-load images by default. To avoid a too abrupt transition with elements appearing into view and then images very obviously loading afterwards, [TwicPics](https://www.twicpics.com/) will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `cachePolicy` | Determines whether to cache images and where: no caching, on disk, in memory or both. Possible values are respectively `none`, `disk`, `memory` or `memory-disk`. When using a value different from `none`, you need to add [Expo Image](https://docs.expo.dev/versions/latest/sdk/image/) as a dependency to your project (see [Installing Expo Modules](#installing-expo-modules)).| `String` | `none` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration). Providing it is **mandatory**.                                                                                                                                                                                                                                                                                                                                   | `String`  |                |
| `env`    | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area.                                                                                            | `String`  | `"production"` |
| `maxDPR` | [TwicPics](https://www.twicpics.com/) will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, [TwicPics](https://www.twicpics.com/) will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number`  | `2`            |
| `path`   | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"`                                                                                                                                                                                                                                                                                                               | `String`  |                |
| `step`   | To avoid requesting too may variants of the same image, [TwicPics](https://www.twicpics.com/) will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio.                                                                                                                                                                                                                                           | `Integer` | `10`           |

## Usage

### Basic usage

```jsx
// MyComponent.jsx

import { TwicImg, TwicVideo } from '@twicpics/components/react-native'

const MyComponent = () => (
  <TwicImg
    src="image.jpg"
    style={styles.customImage}
    mode="cover"
    placeholder="preview"
  />
  <TwicVideo
    src="video.mp4"
    style={styles.customVideo}
    mode="cover"
    placeholder="preview"
  />
)

const styles = StyleSheet.create({
  customImage: {
    // some styles
  },
  customVideo: {
    // some styles
  },
})

export default MyComponent
```

### Image Caching

By default, the `<TwicImg>` component only manages image caching for **web platform**.

If you plan to use image caching for **iOS** or **Android** platforms, you'll need to install [Expo Image](#installing-expo-modules) as a dependency of your project and configure the cache policy as follows:

```js
// App.js

import { installTwicpics } from '@twicpics/components/react-native';

// defines the cache policy for the entire application during setup
installTwicpics({
  "domain": `https://<your-domain>.twic.pics/`,
  "cachePolicy": `disk`, // set the cache policy to 'disk' for persistent storage
});
```

```jsx
// MyComponent.jsx

import { TwicImg } from "@twicpics/components/react-native";

const MyComponent = () => (
  <View>
    <TwicImg 
      src="path/to/your/image" {/* image will be cached to disk as defined in setup options */}
    />
    <TwicImg
      src="path/to/your/image"
      cachePolicy="memory" {/* overrides setup option with `memory` value for in-memory caching  */}
    />
    <TwicImg
      src="path/to/your/image"
      cachePolicy="none" {/* overrides setup option with `none` value: image will not be cached */}
    />
  </View>
);
```

For more information about the possible `cachePolicy` values, please refer to the [Expo Image documentation](https://docs.expo.dev/versions/latest/sdk/image/#cachepolicy).

### Lazy Loading

`TwicImg` and `TwicVideo` will lazy-load assets by default and "anticipate" lazy loading by a factor of the actual viewport. This can be controlled using the [anticipation option](#setup-options).

When embedding `TwicImg` or `TwicVideo` in a lazily loading-compatible Component like [FlatList](https://reactnative.dev/docs/flatlist), it is recommended to disable `TwicImg` or `TwicVideo`'s lazy-loading feature using the `eager` prop:

```jsx
// MyComponent.jsx

import React from 'react';
import { FlatList, View } from 'react-native';
import { TwicImg } from '@twicpics/components/react-native'

const data = [
  // Data containing image URLs
  { id: 1, imageUrl: 'image1.jpg' },
  { id: 2, imageUrl: 'image2.jpg' },
  // More data...
];

const renderItem = ({ item }) => (
  <View>
    <TwicImg
      src={item.imageUrl}
      eager {/* disables lazy loading for this image */} />
  </View>
);

const MyComponent = () => {
  return (
    <FlatList
      data={data}
      renderItem={renderItem}
      keyExtractor={(item) => item.id.toString()}
      // Other FlatList props...
    />
  );
};

export default MyComponent;
```

### Refit Example

The `<TwicImg>` component allows to **reframe** your image on the **main subject(s)** it contains.

In **cover** `mode`, the resulting image will respect`ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image will be cropped as close as possible to the main subject(s).

To activate automatic cropping, simply add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image but it is possible to align the subject with a given border by specifying an `anchor`.

Also by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" />
```

### Working with ratio="none"

Particularly useful when creating hero banner, you can specify the height of your image while respecting its natural aspect ratio and optimizing the _Cumulative Layout Shift_ metric.
When using `ratio="none"` your style **must** specify the image height.

```jsx
// MyComponent.jsx

import { TwicImg } from '@twicpics/components/react-native'

const MyComponent = () => (
  <TwicImg src="path/to/your/image" ratio="none" style={styles.heroImage} />
)

// When using `ratio="none"`, you are responsible for properly sizing the component
const styles = StyleSheet.create({
  heroImage: {
    height: 500,
  },
})

export default MyComponent
```

## Components Properties

### `TwicImg`

This component can be used in place of an `<Image>` component.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  cachePolicy="<none|disk|memory|memory-disk>"
  crossOrigin="<anonymous|use-credentials>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  mode="<contain|cover>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerPolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  step="<integer>"
  style="<Object>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<Function>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | based on `src` |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left` and `bottom-right`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied __after__ an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` |
| `cachePolicy` | Overrides the [global cache policy configuration](setting-up-twicpics-components-in-your-react-native-project) and determines whether to cache the image and where: no caching, on disk, in memory or both. Possible values are respectively `none`, `disk`, `memory` or `memory-disk`. When using a value different from `none`, you need to add [Expo Image](https://docs.expo.dev/versions/latest/sdk/image/) as a dependency to your project (see [Installing Expo Modules](#installing-expo-modules)). | `String` | `none` |
`crossOrigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`crossOrigin property`](https://reactnative.dev/docs/image#crossorigin). | `String` | |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied __after__ `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. You are responsible for properly sizing the component when `ratio="none"`. | `String` | `1` |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String ` | `false` |
`referrerPolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`image referrerpolicy property`](https://reactnative.dev/docs/image#referrerpolicy). | `String` | |
| `src` | Path to the image. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
| `style` | Accepts styles defined in a JavaScript object in the usual React Native style, see [React Native docs](https://reactnative.dev/docs/style). | `Object` | `null` |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | React Native [Easing](https://reactnative.dev/docs/easing) function applied to the transition effect. | `Function` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### `TwicVideo`

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<coordinates>"
  mode="<contain|cover>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  step="<integer>"
  style="<Object>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. | `String` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video.  | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `src` | Path to the video. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
| `style` | Accepts styles defined in a JavaScript object in the usual React Native style, see [React Native docs](https://reactnative.dev/docs/style). | `Object` | `null` |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | React Native [Easing](https://reactnative.dev/docs/easing) function applied to the transition effect. | `Function` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

---

## Svelte 3

# Svelte 3

<illustration src="github/components/main/documentation/resources/svelte-cover.png" width="1906" height="764" alt="TwicPics Svelte Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-svelte3-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project as a dev dependency:

```bash
# Using yarn
yarn add @twicpics/components -D

# Or using npm
npm install @twicpics/components --D
```

> TwicPics Components are available for `Svelte3` version __3.47+__.
> If you are using `Svelte4` or `Svelte5`, you can find their documentation [here](https://www.twicpics.com/docs/components/svelte-4) and [here](https://www.twicpics.com/docs/components/svelte-5) respectively.

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `Svelte3` project

While we recommend going the `ES module` route and use `import` statements, [TwicPics Components](https://www.npmjs.com/package/@twicpics/components) is also backward compatible with `CommonJS` and `require` statements.

Add the import part:

```js
// import TwicPics svelte3 components
import { installTwicpics } from "@twicpics/components/svelte3";
// import TwicPics components css
import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```js
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );
```

into the app startup of your `Svelte3` project.

#### main.js

```js
// Here is an example of a `Svelte3` app startup configured with TwicPics.
import { installTwicpics } from "@twicpics/components/svelte3";
import "@twicpics/components/style.css";

import App from "./App.svelte";

installTwicpics({
  "domain": `https://<your-domain>.twic.pics`
});

const app = new App({
  target: document.body
});

export default app;
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is __mandatory__. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part in the `script` section of your `.svelte` page:

```html
<script>
  // this component will be used in instead of an img element.
  import { TwicImg } from "@twicpics/components/svelte3";

  // this component will be used in instead of a `picture` element.
  import { TwicPicture } from "@twicpics/components/svelte3";

  // this component will be used in instead of an video element.
  import { TwicVideo } from "@twicpics/components/svelte3";
</script>
```

then, use `<TwicImg>`, `<TwicPicture>` or `<TwicVideo>` instead of standard tags `<img>`, `<picture>` or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
</script>

<main>
  <TwicImg src="path/to/your/image"></TwicImg>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicBasicGrid.svelte&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicBulkLoading.svelte&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a __lazy loaded__, zoomed version of your image on __mouseover__.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in __cover__ `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicZoom.svelte&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, binding to `state` props gives access to the loading state of your image or video.

Here are the values the Component will emit :

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
  let state;

  $: {
    // Implement the logic here
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  bind:state
  src="path/to/your/image"
/>
```

Another approach is to listen to the `statechange` event.

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
  let state;

  const handleStateChange = ( e ) => {
    // Implement the logic here
    state = e.detail;
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  on:statechange={handleStateChange}
  src="path/to/your/image"
/>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicState.svelte&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to __reframe__ your image on the __main subject(s)__ they contain.

In __cover__ `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In __contain__ `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicRefit.svelte&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
</script>

<style>
  .landscape {
    --twic-ratio: calc(4 / 3);
  }

  .portrait {
    --twic-ratio: calc(3 / 4);
  }

  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>

<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="sm">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src/lib/TwicStyleDriven.svelte&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
</script>

<style>
  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicArtDirections.svelte&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte3";
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>

<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte3?file=src%2Flib%2FTwicHero.svelte&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.


```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Svelte 4

# Svelte 4

<illustration src="github/components/main/documentation/resources/svelte-cover.png" width="1906" height="764" alt="TwicPics Svelte Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-svelte4-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project as a dev dependency:

```bash
# Using yarn
yarn add @twicpics/components -D

# Or using npm
npm install @twicpics/components --D
```

> TwicPics Components are available for `Svelte4`.
> If you are using `Svelte3` or `Svelte5`, you can find their documentation [here](https://www.twicpics.com/docs/components/svelte-3) and [here](https://www.twicpics.com/docs/components/svelte-5) respectively.

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `Svelte4` project

While we recommend going the `ES module` route and use `import` statements, [TwicPics Components](https://www.npmjs.com/package/@twicpics/components) is also backward compatible with `CommonJS` and `require` statements.

Add the import part:

```js
// import TwicPics Svelte4 components
import { installTwicpics } from "@twicpics/components/svelte4";
// import TwicPics components css
import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```js
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );
```

into the app startup of your `Svelte4` project.

#### main.js

```js
// Here is an example of a `Svelte4` app startup configured with TwicPics.
import { installTwicpics } from "@twicpics/components/svelte4";
import "@twicpics/components/style.css";

import App from "./App.svelte";

installTwicpics({
  "domain": `https://<your-domain>.twic.pics`
});

const app = new App({
  target: document.body
});

export default app;
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part in the `script` section of your `.svelte` page:

```html
<script>
  // this component will be used in instead of an img element.
  import { TwicImg } from "@twicpics/components/svelte4";

  // this component will be used in instead of a `picture` element.
  import { TwicPicture } from "@twicpics/components/svelte4";

  // this component will be used in instead of a video element.
  import { TwicVideo } from "@twicpics/components/svelte4";
</script>
```

then, use `<TwicImg>` or `<TwicVideo>` instead of standard tags `<img>` or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
</script>

<main>
  <TwicImg src="path/to/your/image"></TwicImg>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicBasicGrid.svelte&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicBulkLoading.svelte&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicZoom.svelte&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, binding to `state` props gives access to the loading state of your image or video.

Here are the values the Component will emit :

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
  let state;

  $: {
    // Implement the logic here
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  bind:state
  src="path/to/your/image"
/>
```

Another approach is to listen to the `statechange` event.

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
  let state;

  const handleStateChange = ( e ) => {
    // Implement the logic here
    state = e.detail;
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  on:statechange={handleStateChange}
  src="path/to/your/image"
/>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicState.svelte&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicRefit.svelte&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
</script>

<style>
  .landscape {
    --twic-ratio: calc(4 / 3);
  }

  .portrait {
    --twic-ratio: calc(3 / 4);
  }

  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>

<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="sm">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src/lib/TwicStyleDriven.svelte&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
</script>

<style>
  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicArtDirections.svelte&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte4";
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>

<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte4?file=src%2Flib%2FTwicHero.svelte&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Svelte 5

# Svelte 5

<illustration src="github/components/main/documentation/resources/svelte-cover.png" width="1906" height="764" alt="TwicPics Svelte Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-svelte5-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project as a dev dependency:

```bash
# Using yarn
yarn add @twicpics/components -D

# Or using npm
npm install @twicpics/components --D
```

> TwicPics Components are available for `Svelte5`.
> If you are using `Svelte3` or `Svelte4`, you can find their documentation [here](https://www.twicpics.com/docs/components/svelte-3) and [here](https://www.twicpics.com/docs/components/svelte-4) respectively.


> [Svelte5](https://svelte-5-preview.vercel.app/docs/introduction) is still under development and subject to `numerous modifications`.

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `Svelte5` project

Add the import part:

```js
// import TwicPics Svelte5 components
import { installTwicpics } from "@twicpics/components/svelte5";
// import TwicPics components css
import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```js
installTwicpics( {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics"
} );
```

into the app startup of your `Svelte5` project.

#### main.js

```js
// Here is an example of a `Svelte5` app startup configured with TwicPics.
import { installTwicpics } from "@twicpics/components/svelte5";
import "@twicpics/components/style.css";

import App from "./App.svelte";
import { mount } from 'svelte';

installTwicpics({
  "domain": `https://<your-domain>.twic.pics`
});

const app = mount( Sample, {
  "target": document.body,
} );

export default app;
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part in the `script` section of your `.svelte` page:

```html
<script>
  // this component will be used in instead of an img element.
  import { TwicImg } from "@twicpics/components/svelte5";

  // this component will be used in instead of a `picture` element.
  import { TwicPicture } from "@twicpics/components/svelte5";

  // this component will be used in instead of a video element.
  import { TwicVideo } from "@twicpics/components/svelte5";
</script>
```

then, use `<TwicImg>` or `<TwicVideo>` instead of standard tags `<img>` or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
</script>

<main>
  <TwicImg src="path/to/your/image"></TwicImg>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicBasicGrid.svelte&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicBulkLoading.svelte&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicZoom.svelte&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, binding to `state` props gives access to the loading state of your image or video.

Here are the values the Component will emit :

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
  let state;

  $: {
    // Implement the logic here
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  bind:state
  src="path/to/your/image"
/>
```

Another approach is to listen to the `statechange` event.

```html
<!-- component.svelte -->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
  let state;

  const handleStateChange = ( e ) => {
    // Implement the logic here
    state = e.detail;
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  on:statechange={handleStateChange}
  src="path/to/your/image"
/>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicState.svelte&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicRefit.svelte&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
</script>

<style>
  .landscape {
    --twic-ratio: calc(4 / 3);
  }

  .portrait {
    --twic-ratio: calc(3 / 4);
  }

  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>

<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="sm">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src/lib/TwicStyleDriven.svelte&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
</script>

<style>
  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicArtDirections.svelte&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.svelte-->
<script>
  import { TwicImg } from "@twicpics/components/svelte5";
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>

<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-svelte5?file=src%2Flib%2FTwicHero.svelte&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.


```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## SvelteKit

# SvelteKit

<illustration src="github/components/main/documentation/resources/sveltekit-cover.png" width="1906" height="764" alt="TwicPics Svelte Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-sveltekit-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project as a dev dependency:

```bash
# Using yarn
yarn add @twicpics/components -D

# Or using npm
npm install @twicpics/components --D
```

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `SvelteKit` project

Add the import part:

```js
  // import TwicPics sveltekit components
  import { installTwicpics } from "@twicpics/components/sveltekit";
  // import TwicPics components css
  import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```js
  installTwicpics( {
    // domain is mandatory
    "domain": "https://<your-domain>.twic.pics"
  } );
```

into the main [layout](https://kit.svelte.dev/docs/routing#layout-layout-svelte) of your `SvelteKit` project.

If you don't already have a [layout](https://kit.svelte.dev/docs/routing#layout-layout-svelte) that applies to all the pages of your application, simply create it by adding `+layout.svelte` file, right next to your entry point `src/routes/+page.svelte`.

#### src/routes/+layout.svelte

```html
<script>
  // Here is an example of +layout.svelte file
  import { installTwicPics } from "@twicpics/components/sveltekit";
  import "@twicpics/components/style.css";
  installTwicPics( {
      "domain": `https://<your-domain>.twic.pics`,
  } );
</script>
<slot />
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

Add the import part in the `script` section of your `.svelte` file:

```html
<script>
  // this component will be used in instead of an img element.
  import { TwicImg } from "@twicpics/components/sveltekit";

  // this component will be used in instead of a `picture` element.
  import { TwicPicture } from "@twicpics/components/sveltekit";

  // this component will be used in instead of an video element.
  import { TwicVideo } from "@twicpics/components/sveltekit";
</script>
```

or

```html
<script>
  // this component will be used in instead of an img element.
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";

    // this component will be used in instead of a `picture` element.
  import TwicPicture from "@twicpics/components/sveltekit/TwicPicture.svelte";

  // this component will be used in instead of a video element.
  import TwicVideo from "@twicpics/components/sveltekit/TwicVideo.svelte";
</script>
```

then, use `<TwicImg>`, `<TwicPicture>` or `<TwicVideo>` instead of standard tags `<img>`, `picture`  or `<video>` (see [Components Properties](#components-properties)).

### Basic usage

```html
<!-- component.svelte-->
<script>
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
</script>

<main>
  <TwicImg src="path/to/your/image"></TwicImg>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fbasic-grid%2F%2Bpage.svelte&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fbulk-loading%2F%2Bpage.svelte&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in **cover** `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fzoom%2F%2Bpage.svelte&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, binding `state` props gives access to the loading state of your image or video.

Here are the values the Component will emit :

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<script>
  // component.svelte
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
  let state;

  $: {
    // Implement the logic here
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  bind:state
  src="path/to/your/image"
/>
```

Another approach is to listen to the `statechange` event.

```html
<script>
  // component.svelte
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
  let state;

  const handleStateChange = ( e ) => {
    // Implement the logic here
    state = e.detail;
    console.log( `TwicComponent emits a new state`, state );
  }
</script>


<TwicImg
  on:statechange={handleStateChange}
  src="path/to/your/image"
/>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fstate%2F%2Bpage.svelte&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Frefit%2F%2Bpage.svelte&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<script>
  // component.svelte
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
</script>

<style>
  .landscape {
    --twic-ratio: calc(4 / 3);
  }

  .portrait {
    --twic-ratio: calc(3 / 4);
  }

  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>

<main>
  <div class="landscape">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="square">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="portrait">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="lg">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="md">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
  <div class="sm">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fstyle-driven%2F%2Bpage.svelte&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<script>
  // component.svelte
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
</script>

<style>
  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

<main>
  <div class="style-driven-responsive">
    <TwicImg src="path/to/your/image"></TwicImg>
  </div>
</main>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fart-directions%2F%2Bpage.svelte&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<script>
  // component.svelte
  import TwicImg from "@twicpics/components/sveltekit/TwicImg.svelte";
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>

<TwicImg
  src="path/to/your/image"
  className="hero-image"
  ratio="none"
></TwicImg>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-sveltekit?file=src%2Froutes%2Fhero%2F%2Bpage.svelte&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.


```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  bind:state="<String>"
  on:statechange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `state` | A string property being update each time the asset loading state is updated. Values can be `new`, `loading`, `done` or `error`.| `String` | |
| `statechange` | A custom event dispatched each time the image loading state is updated. Emitted values can be `new`, `loading`, `done` or `error`.| `( e: CustomEvent ) => void` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |


## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Vue 2

# Vue 2

<illustration src="github/components/main/documentation/resources/vuejs-cover.png" width="1906" height="764" alt="TwicPics VueJS Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-vue2-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `Vue2` project

TwicPics components for `Vue2` come as a `Vue2 Plugin` and are configured as [such](https://vuejs.org/guide/reusability/plugins.html).

Add the import part:

```js
// import TwicPics vue2 plugin
import TwicPics from "@twicpics/components/vue2";
// import TwicPics components css
import "@twicpics/components/style.css";
```

and use TwicPics Components Plugin with [Setup Options](#setup-options)

```js
Vue.use(TwicPics, {
  domain: "https://<your-domain>.twic.pics"
});
```

into the app startup of your `Vue2` project.

#### main.js

```js
// Here is an example of a `Vue2` app startup configured with TwicPics.
import Vue from "vue";
import App from "./App.vue";

// import TwicPics plugin
import TwicPics from "@twicpics/components/vue2";
import "@twicpics/components/style.css";

// configure TwicPics plugin
Vue.use(TwicPics, {
  domain: "https://<your-domain>.twic.pics"
});

new Vue({
  render: (h) => h(App)
}).$mount("#app");

```

__Changing components names__

You can change how components are named using the `TwicImg` and/or `TwicVideo` options when calling `use`:

```js
Vue.use( TwicPics, {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics",
  "TwicImg": "Batman"
} );
```

You can then reference the component using the alternate name:

```html
<template>
  <Batman src="path/to/your/image"/>
</template>
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is __mandatory__. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

```html
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

### Basic usage

```html
<!-- component.vue -->
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src%2Fcomponents%2FTwicBasicGrid.vue&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src/components/TwicBulkLoading.vue&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a __lazy loaded__, zoomed version of your image on __mouseover__.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in __cover__ `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src%2Fcomponents%2FTwicZoom.vue&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, passing a callback function to the `stateChange` emitter gives access to your image's or video's loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg
        src="path/to/your/image"
        @stateChange="handleStateChange"
      />
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
  data() {
    state:undefined
  },
  methods: {
    handleStateChange( stateEvent ) {
      // Implement the logic here
      const { state } = stateEvent;
      this.state = state;
      console.log( `TwicComponent emits a new state`, this.state );
    }
  }
};
</script>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src%2Fcomponents%2FTwicState.vue&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to __reframe__ your image on the __main subject(s)__ they contain.

In __cover__ `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In __contain__ `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src%2Fcomponents%2FTwicRefit.vue&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.vue -->
<template>
  <main>
    <div class="twic-item landscape">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item square">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item portrait">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item contain left">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item contain right">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item lg">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item md">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item sm">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
    <div class="cover square">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.landscape {
  --twic-ratio: calc(4 / 3);
}
.portrait {
  --twic-ratio: calc(3 / 4);
}
.square {
  --twic-ratio: calc(1);
}

.lg {
  width: 300px;
}

.md {
  width: 150px;
}

.sm {
  width: 100px;
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src/components/TwicStyleDriven.vue&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.style-driven-responsive {
  --twic-ratio: calc(2 / 3);
  --twic-mode: cover;
  margin: auto;
}

@media (min-width: 640px) {
  .style-driven-responsive {
    --twic-ratio: calc(1);
  }
}

@media (min-width: 768px) {
  .style-driven-responsive {
    --twic-ratio: calc(4 / 3);
  }
}

@media (min-width: 1024px) {
  .style-driven-responsive {
    --twic-ratio: calc(16 / 9);
  }
}

@media (min-width: 1280px) {
  .style-driven-responsive {
    --twic-ratio: calc(1.85);
  }
}

@media (min-width: 1536px) {
  .style-driven-responsive {
    --twic-ratio: calc(21 / 9);
  }
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src/components/TwicArtDirections.vue&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.vue -->
<template>
  <TwicImg
    src="path/to/your/image"
    class="hero-image"
    ratio="none"
 ></TwicImg>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue2?file=src%2Fcomponents%2FTwicHero.vue&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `stateChange` emitter:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Vue 3

# Vue 3

<illustration src="github/components/main/documentation/resources/vuejs-cover.png" width="1906" height="764" alt="TwicPics VueJS Components"></illustration>

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

Discover our demonstrations and integration examples [in our online demo project](https://twicpics-vue3-demo.netlify.app/?utm_source=twicpics&utm_medium=organic&utm_campaign=documentation).

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your `Vue3` project

TwicPics components for `Vue3` come as a `Vue3 Plugin` and are configured as [such](https://vuejs.org/guide/reusability/plugins.html).

Add the import part:

```js
// import TwicPics vue3 plugin
import TwicPics from "@twicpics/components/vue3";
// import TwicPics components css
import "@twicpics/components/style.css";
```

and use TwicPics Components Plugin with [Setup Options](#setup-options)

```js
// app is the application instance 
app.use(TwicPics, {
  domain: "https://<your-domain>.twic.pics"
});
```

into the app startup of your `Vue3` project.

#### main.js

```js
// Here is an example of a `Vue3` app startup configured with TwicPics.
import App from "./App.vue";
import { createApp } from "vue";

// import TwicPics Vue3 Plugin
import TwicPics from "@twicpics/components/vue3";
import "@twicpics/components/style.css";

// create application instance
const app = createApp(App);

// configure TwicPics Vue3 Plugin
app.use(TwicPics, {
  domain: "https://<your-domain>.twic.pics"
});

app.mount("#app");
```

__Changing components names__

You can change how components are named using the `TwicImg` and/or `TwicVideo` options when calling `use`:

```js
app.use( TwicPics, {
  // domain is mandatory
  "domain": "https://<your-domain>.twic.pics",
  "TwicImg": "Batman"
} );
```

You can then reference the component using the alternate name:

```html
<template>
  <Batman src="path/to/your/image"/>
</template>
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is __mandatory__. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

Import TwicPics Components such as `TwicImg`, `TwicPicture`, or `TwicVideo` into your template files.

Replace standard `img`, `picture`, or `video` tags with these components to enhance functionality and customization (see [Components Properties](#components-properties)).

```html
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

### Basic usage

```html
<!-- component.vue -->
<template>
  <main>
    <TwicImg src="path/to/your/image"/>
  </main>
</template>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwicBasicGrid.vue&initialpath=basic-grid)

### Bulk loading with TwicView

By default, `<TwicImg>` and `<TwicVideo>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<TwicImg>` and `<TwicVideo>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <TwicImg src="image1.jpg" />
  <TwicImg src="image2.jpg" />
  <TwicImg src="image3.jpg" />
</TwicView>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwicBulkLoading.vue&initialpath=bulk-loading)

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<TwicImg>` component lets you display a __lazy loaded__, zoomed version of your image on __mouseover__.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <TwicImg src="image1.jpg" zoom="2" />
  <TwicImg src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <TwicImg src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `TwicImg` component in __cover__ `mode`.

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwicZoom.vue&initialpath=zoom)

### Lifecycle

For `TwicImg` and `TwicVideo` components, passing a callback function to the `stateChange` emitter gives access to your image's or video's loading state.

Here are the values the Component will emit ([see State Type definition](#loading-state-values)):

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg
        src="path/to/your/image"
        @stateChange="handleStateChange"
      />
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
  data() {
    state:undefined
  },
  methods: {
    handleStateChange( stateEvent ) {
      // Implement the logic here
      const { state } = stateEvent;
      this.state = state;
      console.log( `TwicComponent emits a new state`, this.state );
    }
  }
};
</script>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwicState.vue&initialpath=state)

### Refit example

`<TwicImg>` and `<TwicPicture>` components allow to __reframe__ your image on the __main subject(s)__ they contain.

In __cover__ `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In __contain__ `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <TwicImg src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <TwicImg src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <TwicImg src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <TwicImg src="image3.jpg" refit="5p,10p" />
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwiRefit.vue&initialpath=refit)

### Style-Driven Approach

You can set up `TwicImg` and `TwicVideo` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- component.vue -->
<template>
  <main>
    <div class="twic-item landscape">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item square">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item portrait">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item contain left">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item contain right">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
    <div class="twic-item lg">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item md">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <div class="twic-item sm">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
    <!---
    Attributes take precedence over CSS.
    In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
--->
    <div class="cover square">
      <TwicImg src="path/to/your/image" ratio="16/9"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.landscape {
  --twic-ratio: calc(4 / 3);
}
.portrait {
  --twic-ratio: calc(3 / 4);
}
.square {
  --twic-ratio: calc(1);
}

.lg {
  width: 300px;
}

.md {
  width: 150px;
}

.sm {
  width: 100px;
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src/views/TwicStyleDriven.vue&initialpath=style-driven)

### Responsive Example

Setting up `TwicImg` and `TwicVideo` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- component.vue -->
<template>
  <main>
    <div class="style-driven-responsive">
      <TwicImg src="path/to/your/image"></TwicImg>
    </div>
  </main>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
.style-driven-responsive {
  --twic-ratio: calc(2 / 3);
  --twic-mode: cover;
  margin: auto;
}

@media (min-width: 640px) {
  .style-driven-responsive {
    --twic-ratio: calc(1);
  }
}

@media (min-width: 768px) {
  .style-driven-responsive {
    --twic-ratio: calc(4 / 3);
  }
}

@media (min-width: 1024px) {
  .style-driven-responsive {
    --twic-ratio: calc(16 / 9);
  }
}

@media (min-width: 1280px) {
  .style-driven-responsive {
    --twic-ratio: calc(1.85);
  }
}

@media (min-width: 1536px) {
  .style-driven-responsive {
    --twic-ratio: calc(21 / 9);
  }
}
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src/views/TwicArtDirections.vue&initialpath=art-directions)

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- component.vue -->
<template>
  <TwicImg
    src="path/to/your/image"
    class="hero-image"
    ratio="none"
 ></TwicImg>
</template>

<script>
export default {
  name: "App",
};
</script>

<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/TwicPics/components-demo-vue3?file=src%2Fviews%2FTwicHero.vue&initialpath=hero)

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.


```html
<TwicImg
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<TwicVideo
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  @stateChange="<function>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `stateChange` | An event dispatched each time the asset loading state is updated. State can be `new`, `loading`, `done` or `error`.| [`( stateEvent: StateEvent ) => void`](#loading-state-values) | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |


### Loading State Values

Union type for all possible image or video loading states:

```ts
type State = `error` | `done` | `loading` | `new`;
```

- `new`: when the `img` or `video` source has not started loading
- `loading`: when the `img` or `video` source is loading
- `done`: when the `img` or `video` source has successfully loaded
- `error`: when an error occurred while loading the `img` or `video` source

### State Change Event

Data type passed as a parameter to the `stateChange` emitter:

```ts
export type StateEvent = {
  target: TwicImg | TwicVideo,
  state: State
};
```

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `TwicImg` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---

## Web Components

# Web Components

<illustration src="github/components/main/documentation/resources/webcomponents-cover.png" width="1906" height="764" alt="TwicPics Web Components"></illustration>

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

<code-sandbox-button title="Edit web-component - Basic" link="https://codesandbox.io/s/web-component-basic-19j1fm?fontsize=14&hidenavigation=1&theme=dark"></code-sandbox-button>

> Every single Shadow DOM the TwicPics components are descendants of must be opened. That's the only way the TwicPics Script will be able to reach them.

## Installation

Add the `@twicpics/components` package to your project:

```bash
# Using yarn
yarn add @twicpics/components

# Or using npm
npm install @twicpics/components
```

## Setup

> You will need a TwicPics domain to initialize the package. [Create an account for free](https://account.twicpics.com/signup?utm_source=github&utm_medium=organic&utm_campaign=components) to get your domain.

### Setting up TwicPics Components in your project

While we recommend going the `ES module` route and use `import` statements, [TwicPics Components](https://www.npmjs.com/package/@twicpics/components) is also backward compatible with `CommonJS` and `require` statements.

Add the import part:

```jsx
// import TwicPics webcomponents
import { installTwicpics } from "@twicpics/components/webcomponents";
// import TwicPics components css
import "@twicpics/components/style.css";
```

And the configuration part (see [Setup Options](#setup-options)):

```js
installTwicpics( {
  // domain is mandatory
  "domain": `https://<your-domain>.twic.pics`
} );
```

into the main js file of your project.

```js
// Here is an example of a main file configured with TwicPics.
import { installTwicpics, TwicImg } from "@twicpics/components/webcomponents";

installTwicpics( {
  // domain is mandatory
  "domain": `https://<your-domain>.twic.pics`
} );

customElements.define( `twic-img`, TwicImg );
```

```html
// Other example with configuration embeded in an html file
// and a full client side consideration
<script type="module">
  import {
    installTwicpics,
    TwicImg
  } from "./node_modules/@twicpics/components/webcomponents/module.mjs";

  installTwicpics({
    "domain": `https://<your-domain>.twic.pics`
  });

  // define the custom element alias
  customElements.define(`twic-img`, TwicImg);
</script>
```

### Setup Options

| Option | Description | Type | Default |
|:-|:-|:-|:-|
| `anticipation` | TwicPics will lazy-load images by default. To avoid too abrupt a transition with elements appearing into view and then images very obviously loading afterwards, TwicPics will "anticipate" lazy loading by a factor of the actual viewport. This behavior is controlled by this setting. | `Number` | `0.2` |
| `breakpoints`| Customizes breakpoints value for responsive behavior. | `object` | `{ xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` |
| `domain` | This is your very own [TwicPics domain](https://www.twicpics.com/docs/essentials/domain-configuration?utm_source=github&utm_medium=organic&utm_campaign=components). Providing it is **mandatory**. | `String` | |
| `env` | Can be `debug`, `offline` or `production`. When set to `debug`, a gray lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders?utm_source=github&utm_medium=organic&utm_campaign=components) that displays its intrinsic dimensions is displayed in place of all medias targeted by their `src` value. When set to `offline`, these medias are replaced by a simple placeholder that allows to visualise their display area. | `String` | `"production"` |
| `handleShadowDom` | Must be set to `true` when using TwicComponents within a shadow DOM. | `boolean` | `false` |
| `maxDPR` | TwicPics will take the "Device Pixel Ratio" (`DPR`) of the current device into consideration when determining the sizes of images to load. By default, it will not take a `DPR` greater than `2` into consideration. If the `DPR` of the device is higher than `2`, TwicPics will assume it to be `2`. Using `maxDPR`, you can lower this limit down to `1` or be more permissive (for instance by setting it to `3` or `4`). | `Number` | `2` |
| `path` | Path to prepend to all src attributes. For instance, if path is `"some/folder"` then a src attribute set to `"image.jpg"` will be expanded into `"some/folder/image.jpg"` | `String` | |
| `step` | To avoid requesting too may variants of the same image, TwicPics will round the width of images to the closest multiple of step. The height will then be computed in order to respect the original aspect ratio. | `Integer` | `10` |

## Usage

TwicPics Web Components comes as `Custom Html Elements`. Just use them instead of `img`, `picture` or `video` tags according to the custom alias you have specified.

```html
<twic-img src="path/to/your/image"/>
```

More properties [here](#components-properties).

### Basic usage

```html
<!-- page.html -->
<body>
    <twic-img src="path/to/your/image"/>
</body>
```

### Bulk loading with TwicView

By default, `<twic-img>` and `<twic-video>` will only start loading when they enter the viewport. But sometimes, you may want to load multiple assets in bulk instead of lazy loading them. This is where `<TwicView>` comes into play.

The `<TwicView>` component eagerly loads all of his `<twic-img>` and `<twic-video>` children as soon as it enters the viewport (depending on your [anticipation settings](#setup-options).)

For example, if you're building a carousel, you might want to bulk-load all images. In the following code, all three images will be loaded when `TwicView` comes into the viewport:

```html
<TwicView>
  <twic-img src="image1.jpg" />
  <twic-img src="image2.jpg" />
  <twic-img src="image3.jpg" />
</TwicView>
```

### Critical Images

`TwicPicture` streamlines the use of `picture` elements and `srcset` attributes.

It operates independently of [TwicPics Native](https://www.twicpics.com/docs/essentials/native) and dynamically generates `source` elements and `srcset` attributes from a single master file using variants transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).

#### Resolution switching

The following examples illustrate how to serve different resolutions of the same image according to `breakpoints` and `maxDPR` defined in [Setup Options](#setup-options).

```html
<!-- Populate srcset and fallback with a list of squared variants -->
<TwicPicture src="your-lcp-image.jpg"></TwicPicture>
```

```html
<!-- Populate srcset and fallback with a list of 16/9 variants -->
<TwicPicture
  src="your-lcp-image.jpg"
  ratio="16/9"
></TwicPicture>
```

```html
<!-- eager disables lazy-loading and sets fetchpriority to high -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
></TwicPicture>
```

```html
<!-- for best performances set sizes attribute is a best practice -->
<TwicPicture
  src="your-lcp-image.jpg"
  eager
  sizes="
    (min-width: 1000px) 33vw,
    96vw
  "
></TwicPicture>
```

For a comprehensive list of properties and detailed information, please refer to [TwicPicture](#twicpicture).

<a name="art-direction"></a>
#### Art Direction

To achieve _art direction_, configure the following `TwicPicture`'s properties following the **mobile-first principle**:

- anchor
- focus
- mode
- position
- preTransform
- ratio

The following examples illustrate how to serve various image variations based on distinct _artistic directions_ and [default breakpoint values](#default-breakpoints):

```html
<!--
  This will display a :
  squared variant (default ratio) for screen with a width < 1024 px
  4/3 variant for screen with a width >= 1024 px
  21/9 variant for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
/>

<!--
  This allows to change the focus point for screen with a width >= 1280 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="@xl top"
/>

<!--
  This allows to set the cropping and focus point for small device
  and reset the setting for screen with a width >= 768 px
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  preTransform="
    crop=1000x1000@0.25sx0.25s
    @md none
  "
  focus="
    0.5sx1s
    @md none
  "
/>

<!--
  You can also configure a custom breakpoint
-->
<TwicPicture
  src="art.jpg"
  alt="Art Direction Example"
  ratio="
    @lg 4/3
    @xl 21/9
  "
  focus="
    @666 bottom
    @xl top
  "
/>
```

[Default breakpoint values](#default-breakpoints) can be configured [here](#setup-options).

### Image magnifier

The `<twic-img>` component lets you display a **lazy loaded**, zoomed version of your image on **mouseover**.

To activate the zoom feature, set the `zoom` property to a number strictly greater than 1. This number represents the magnification factor of your image.

For example:

```html
  <twic-img src="image1.jpg" zoom="2" />
  <twic-img src="image2.jpg" zoom="2.5" />
```

The zoom factor can also be configured through the `--twic-zoom` [CSS variable](#css-variables).

To activate the [style-driven zoom](#style-driven-approach), set the `zoom` property to `'css'` and add a new rule to your stylesheet.

For example:

```html
  <twic-img src="image3.jpg" zoom="css" class=".zoom-3"/>
```

```css
.zoom-3 {
  --twic-zoom:3;
}
```

It applies only to the `twic-img` component in **cover** `mode`.

### Refit example

`<twic-img>` and `<TwicPicture>` components allow to **reframe** your image on the **main subject(s)** they contain.

In **cover** `mode`, the resulting image will respect the `ratio` while maximizing the area occupied by the main subject(s).

In **contain** `mode`, the image is cropped as close as possible to the main subject(s).

To activate automatic cropping, add the `refit` property to your component.

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an `anchor`.

Also, by default, the subject will touch the borders of the resulting image. This can be avoided by setting `refit` with a comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) value defining padding.

For example:

```html
  <!-- default refit: centered object(s), no padding around -->
  <twic-img src="image1.jpg" refit />

  <!-- main subject(s) will be left aligned -->
  <twic-img src="image3.jpg" anchor="left" refit/>

  <!-- a 5% padding will be applied around main subject(s) -->
  <twic-img src="image2.jpg" refit="5p" />

  <!-- a 5% padding will be applied vertically, a 10% padding will be applied horizontally -->
  <twic-img src="image3.jpg" refit="5p,10p" />
```

### Style-Driven Approach

You can set up `twic-img` and `twic-video` components using pure CSS and the power of [CSS variables](#css-variables).

```html
<!-- page.html -->
<style>
  body {
    background-color: #342d4e;
    color: #fff;
  }

  main {
    margin-left: auto;
    margin-right: auto;
    max-width: 75%;
  }

  .twic-item {
    margin-bottom: 1rem;
  }

  .landscape {
    --twic-ratio: calc(4 / 3);
  }
  .portrait {
    --twic-ratio: calc(3 / 4);
  }
  .square {
    --twic-ratio: calc(1);
  }

  .lg {
    width: 300px;
  }

  .md {
    width: 150px;
  }

  .sm {
    width: 100px;
  }
</style>

<body>
  <main>
    <div class="twic-item landscape">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item square">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item portrait">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item contain left">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item contain right">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item lg">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item md">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <div class="twic-item sm">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
    <!---
      Attributes take precedence over CSS.
      In the next example, ratio will 16/9 AND NOT 1 as defined in square css class 
  --->
    <div className="cover square">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
  </main>
</body>
```

<a href="https://codesandbox.io/s/web-component-style-driven-o0xfmd?fontsize=14&hidenavigation=1&theme=dark">
  <img alt="Edit web-component - Style Driven" src="https://codesandbox.io/static/img/play-codesandbox.svg">
</a>

### Responsive Example

Setting up `twic-img` and `twic-video` components using CSS and [CSS variables](#css-variables) enables hassle-free responsive designs.

Your template features a single component that will follow your CSS directives and behave responsively.

```html
<!-- page.html -->
<style>
  main {
    margin-left: auto;
    margin-right: auto;
    max-width: 75%;
  }

  .style-driven-responsive {
    --twic-ratio: calc(2 / 3);
    --twic-mode: cover;
    margin: auto;
  }

  @media (min-width: 640px) {
    .style-driven-responsive {
      --twic-ratio: calc(1);
    }
  }

  @media (min-width: 768px) {
    .style-driven-responsive {
      --twic-ratio: calc(4 / 3);
    }
  }

  @media (min-width: 1024px) {
    .style-driven-responsive {
      --twic-ratio: calc(16 / 9);
    }
  }

  @media (min-width: 1280px) {
    .style-driven-responsive {
      --twic-ratio: calc(1.85);
    }
  }

  @media (min-width: 1536px) {
    .style-driven-responsive {
      --twic-ratio: calc(21 / 9);
    }
  }
</style>

<body>
  <main>
    <div class="style-driven-responsive">
      <twic-img src="path/to/your/image"></twic-img>
    </div>
  </main>
</body>

```

<a href="https://codesandbox.io/s/web-component-art-direction-xdyumx?fontsize=14&hidenavigation=1&theme=dark">
  <img alt="Edit web-component - Art Direction" src="https://codesandbox.io/static/img/play-codesandbox.svg">
</a>

### Working with ratio="none"

#### With TwicPicture

It is helpful if you want to display an image with its intrinsic aspect ratio without cropping.

When using `ratio="none"`, there is no CLS optimization, and you are responsible for it.

```html
<!-- will display your image with it's intrinsic ratio, without any cropping -->
<TwicPicture>
  src="path/to/your/image"
  ratio="none"
</TwicPicture>
```

#### With TwicImg and TwicVideo

It is particularly useful when creating a "hero" banner. You can specify the height of your image while respecting its natural aspect ratio, and optimizing your _Cumulative Layout Shift_ (CLS) metric.

When using `ratio="none"`, you are responsible for properly sizing the component.

```html
<!-- page.html -->
<style>
  /* You are responsible for properly sizing the component. */
  .hero-image {
    height:500px;
  }

  @media (min-width: 1024px) {
    .hero-image {
      height:300px;
      width:100%;
    }
  }
</style>

<body>
  <main>
      <twic-img
        src="path/to/your/image"
        class="hero-image"
        ratio="none"
      ></twic-img>
  </main>
</body>
```

<a href="https://codesandbox.io/s/web-component-hero-image-7jdll8?fontsize=14&hidenavigation=1&theme=dark">
  <img alt="Edit TwicPics x Web Component - Hero Image" src="https://codesandbox.io/static/img/play-codesandbox.svg">
</a>

## Components Properties

### TwicImg

This component is a drop-in replacement for the `img` tag dedicated to content images.

It offers advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<twic-img
  src="<path>"
  alt="<String>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
  zoom="<number|String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the component is mounted. This effectively means disabling lazy loading for this image. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** image, formatted `<width>x<height>` (eg. 1920x1080). It prevents image upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** image. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `src` | Path to the image. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent image. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the image will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |
| `zoom` | Enables zoom feature and sets the magnification factor. Must be a number strictly greater than 1 as in `"1.5"` or `1.5`. When set to `'css'`, magnification factor is defined through the CSS variable `--twic-zoom`.Should only be applied to images in cover `mode`. See [Image magnifier](#image-magnifier).| `String | number` | `1` |

### TwicPicture

This component serves as a seamless replacement for the `picture` element.

With a primary focus on maximizing the _Largest Contentful Paint_ (LCP) score with optimized _Cumulative Layout Shift_ (CLS), it effortlessly generates the `srcset` and `source` attributes for _resolution switching_ and _art direction_, all derived from a **single master file** transformed through the [TwicPics API](https://www.twicpics.com/docs/essentials/api).


```html
<TwicPicture
  src="<path>"
  aria-*="<String>"
  alt="<String>"
  anchor="<String>"
  crossorigin="<anonymous|use-credentials>"
  decoding="<async|auto|none|sync>"
  draggable="<boolean>"
  eager="<boolean>"
  fetchpriority="<high|low|auto>"
  focus="<auto|coordinates>"
  id="<String>"
  mode="<contain|cover>"
  position="<String>"
  preTransform="<String>"
  ratio="<ratio>"
  referrerpolicy="<no-referrer|no-referrer-when-downgrade|origin|`origin-when-cross-origin|same-origin|strict-origin|strict-origin-when-cross-origin|unsafe-url>"
  refit="<boolean|String>"
  role="<String>"
  sizes="<String>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `alt` | `alt` attribute content | `String` | |
| `anchor` | Positions the image in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. [Can be set at different breakpoints](#art-direction). | `String` |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the image fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
| `decoding` | Specifies how the browser should decode the image. See [`HTML image decoding attribute`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding). | `String` |  |
`draggable` | Specifies whether the image is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `eager` | Load the image as soon as the `picture` element is processed and set `fetchpriority` to `high`. This effectively means disabling lazy loading for this image. Recommended for optimal Largest Contentful Paint (LCP) display. | `boolean` | `false` |
| `fetchpriority` | Acts as standard [fetchpriority property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority). Can be `high`, `low`or `auto`. Defaults to `high` when `eager` is true. | `string` | |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. [Can be set at different breakpoints](#art-direction). | `String` | |
`id` | Specifies a unique `id` for the image. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). [Can be set at different breakpoints](#art-direction). | `String` | `cover` |
| `position` | Positions the image in `contain` mode. `position` takes precedence over `anchor` when both are provided. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. [Can be set at different breakpoints](#art-direction). | `String` | `center` |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the image (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! [Can be set at different breakpoints](#art-direction).| `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, the image is displayed with its intrinsic aspect ratio. In this case, you are responsible for optimizing the Cumulative Layout Shift (CLS). [Can be set at different breakpoints](#art-direction). | `String or number` | `1` |
| `referrerpolicy` | Specifies the [referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) to use when fetching the image. See the [`HTML image referrerpolicy attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy). | `String` | |
| `refit` | Reframes the image to maximize the area occupied by the main object(s) while respecting `ratio` in `cover` mode. Crops the image as close as possible to the main object(s) in `contain` mode. Can be `true`, `false` or a list of comma-separated [length](https://www.twicpics.com/docs/reference/parameters#length) defining padding. See the [TwicPics refit documentation](https://www.twicpics.com/docs/reference/transformations#refit) for more information.| `boolean or String` | `false` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | `img` |
| `sizes` | Specifies the layout width of the image for each breakpoints using media query syntax. The value of this parameter has a significant impact on performance. Ensure to configure it carefully. See [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).| `String` | |
| `src` | Path to the image. | `String` | |
`style` | Defines inline `CSS` styles for the image. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the image. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
`tabindex` | Specifies the tab order of the image. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |

### TwicVideo

This component is a drop-in replacement for `video`.

It provides seamless playback for [videos optimized with TwicPics](https://www.twicpics.com/docs/guides/video-optimization), offering advanced features like optimized _Cumulative Layout Shift_ (CLS), _Low-Quality Image Placeholder_ (LQIP), and lazy loading out of the box.

```html
<twic-video
  src="<path>"
  anchor="<String>"
  aria-*="<String>"
  bot="<String>"
  crossorigin="<anonymous|use-credentials>"
  draggable="<boolean>"
  duration="<String|number>"
  eager="<boolean>"
  from="<String|number>"
  focus="<auto|coordinates>"
  id="<String>"
  intrinsic="<String>"
  mode="<contain|cover>"
  position="<css position>"
  posterFrom="<String|number>"
  placeholder="<preview|maincolor|meancolor|none>"
  preTransform="<String>"
  ratio="<ratio>"
  role="<String>"
  step="<integer>"
  style="<Object|String>"
  tabindex="<integer>"
  title="<String>"
  to="<String|number>"
  transition="<fade|zoom|none>"
  transitionDelay="<String>"
  transitionDuration="<String>"
  transitionTimingFunction="<String>"
/>
```

| Attribute | Description | Type | Default |
|:-|:-|:-|:-|
| `anchor` | Positions the video in both `contain` and `cover` mode. Accepted values are `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right` and `center`. `position` and `focus` take precedence in `contain` and `cover` mode respectively. Please note that `anchor` is applied **after** an eventual `preTransform`. When using `refit` in `cover` mode, `anchor` aligns the main object(s) with the given border side. | `String` | |
`aria-*` | Specifies accessibility information for assistive technologies. See [ARIA Attributes page](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes). | `String` | |
| `bot` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed for search engine bots. This overrides all other transformations when provided, even if empty (i.e `bot=""`). See the [TwicPics bot attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-bot) for more information. | `String` | |
`crossorigin` | Specifies the [`CORS`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for the video fetch request. See [`HTML crossorigin attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin). | `String` | |
`draggable` | Specifies whether the video is draggable. See [`global attribute draggable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/draggable). | `boolean` | `false` |
| `duration` | Limits the duration of the video. `duration` is expressed in seconds and must be a positive number. `duration` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [duration documentation](https://www.twicpics.com/docs/reference/transformations#duration). | `String or number` | |
| `eager` | Load the video as soon as the component is mounted. This effectively means disabling lazy loading for this video. | `boolean` | `false` |
| `focus` | Sets the focus point in `cover` mode. `focus` takes precedence over `anchor` when both are provided. See the [TwicPics focus attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-focus) for more information. Only use this attribute if you need a specific focus point or if you want to leverage smart cropping with `focus="auto"`: if you only need border-based positioning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | |
| `from` | Moves the starting point of the video. `from` is expressed in seconds and must be a positive number. `from` will not move the end point of the video: to do so, you'll have to use the `duration` or `to` properties. See from documentation. See [from documentation](https://www.twicpics.com/docs/reference/transformations#from). | `String or number` | |
`id` | Specifies a unique `id` for the video. See [`global attribute id`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | `String` | |
| `intrinsic` | Dimensions in pixels of the **original** video, formatted `<width>x<height>` (eg. 1920x1080). It prevents video upscaling and limits the number of generated variants. If using `preTransform`, you should specify the intrinsic dimensions of the **resulting** video. Using incorrect values can lead to display issues, see the [intrinsic attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-intrinsic).| `String` | |
| `mode` | Can be `contain` or `cover` and determines if the video fills the area and is cropped accordingly (`cover`) or if the video will sit inside the area with no cropping (`contain`). | `String` | `cover` |
| `placeholder` | Can be `preview`, `meancolor`, `maincolor` or `none`. See the [TwicPics output transformation documentation](https://www.twicpics.com/docs/reference/transformations#output) for more information. Setting will be overridden to `none` when using `zoom` `transition`. | `String` | `preview` | 
| `position` | Positions the video in `contain` mode. `position` takes precedence over `anchor` when both are provided. Syntax is the same as for CSS position properties [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) and [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Only use this attribute if you need precise positionning: if you only need border-based positionning (`top`, `bottom`, `left`, `right`, etc), use `anchor` instead. | `String` | `center` |
| `posterFrom` | Determines which frame of the source video should be used as a poster / preview. `posterFrom` is expressed in seconds and must be a positive number. By default `posterFrom` is equal to 0, meaning the very first frame of the video is used. `posterFrom` will not modify the video in any way: to do so, you'll have to use the `duration`, `from` or `to` properties. | `String or number` | |
| `preTransform` | A slash-separated list of [TwicPics API transformations](https://www.twicpics.com/docs/reference/transformations) to be performed before resizing the video (see the [TwicPics Manipulation documentation](https://www.twicpics.com/docs/reference/transformations)). Note that `anchor` and `focus` are applied **after** `preTransform`: if you need to specify a specific focus point for your `preTransform` then it needs to be part of the expression (like `preTransform="focus=auto/crop=50px50p"` for instance). Be aware that using this option can lead to unexpected results so use with caution! | `String` | |
| `ratio` | A unitless `width/height` or `width:height` value pair (as in `4/3` or `4:3`) that defines the aspect ratio of the display area. If `height` is not specified, it is assumed to be `1`. A square area will be created by default. When set to `none`, ratio is determined based on width and height as computed by the browser following your `CSS` definitions. The `--twic-ratio` CSS variable is ignored in this instance. You are responsible for properly sizing the component when `ratio="none"`. | `String or number` | `1` |
| `role` | Specifies the [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) of the container. | `String` | |
| `src` | Path to the video. When not provided, a red lightweight `svg` [placeholder](https://www.twicpics.com/docs/reference/placeholders) that displays its intrinsic dimensions is displayed in place of the absent video. When [env](#setup-options) is set to `offline`, that red lightweight `svg` is replaced by a simple red placeholder. | `String` | |
| `step` | See the [TwicPics step attribute documentation](https://www.twicpics.com/docs/reference/native-attributes#data-twic-step) for more information. | `Integer` | `10` |
`style` | Defines inline `CSS` styles for the video. See [`global attribute style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style). | `Object or String` | |
| `title` | `title` representing information related to the video. See [`global attribute title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title). | `String` | |
| `to` | Moves the end point of the video. `to` is expressed in seconds and must be a positive number. `to` will not move the starting point of the video: to do so, you'll have to use the `from` property. See [to documentation](https://www.twicpics.com/docs/reference/transformations#to). | `String or number` | |
`tabindex` | Specifies the tab order of the video. See [`global attribute tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). | `Integer` | |
| `transition` | Determines how the video will be revealed once loaded. With a fade in effect (`fade`), a zoom effect (`zoom`) or without any transition (`none`). Unsupported values are handled as `fade`. | `String` | `fade` |
| `transitionDuration` | Duration of the transition effect. | `String` | `400ms` |
| `transitionTimingFunction` | CSS timing function applied to the transition effect. | `String` | `ease` |
| `transitionDelay` | Transition delay of the transition effect. | `String` | `0ms` |

## CSS Variables

List of variables that can be used to configure your components using pure CSS:

```css
<selector> {
  --twic-ratio: <ratio>;
  --twic-mode: <contain|cover>;
  --twic-position: <css position>;
  --twic-transition-delay: <string>;
  --twic-transition-duration: <string>;
  --twic-transition-timing-function:<string>;
  --twic-zoom:<number>;
}
```

Each CSS variable corresponds to one of the components attributes listed in the [Components Properties section](#components-properties). If present, the attribute takes precedence over the corresponding CSS variable.

| Variable | Description | HTML Attribute | Default |
|:-|:-|:-|:-|
| `--twic-mode` | Can be `contain` or `cover` and determines if the image fills the area and is cropped accordingly (`cover`) or if the image will sit inside the area with no cropping (`contain`). | `mode` | `cover` |
| `--twic-position` | Only useful in `contain` mode. Locates the image inside the area. Syntax is the same as for CSS position properties like [background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) or [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position). Useful values are `top`, `bottom`, `left`, `right`, `left top`, `left bottom` and so on. | `position` | `center` |
| `--twic-ratio` | Floating point value corresponding to a unitless `width/height` ratio (as in `calc(4/3)` or `1.333`). Ratio will correspond to a square area by default. | `ratio` | `1` |
| `--twic-transition-delay` | [Transition delay of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay) | `transitionDelay` | `0ms` |
| `--twic-transition-duration` | [Duration of the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration) | `transitionDuration` | `400ms` |
| `--twic-transition-timing-function` | [CSS timing function applied to the transition effect.](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) | `transitionTimingFunction` | `ease` |
| `--twic-zoom` | Strictly greater than 1 floating point value corresponding to the zoom factor to be applied. Only applies to `twic-img` with `zoom` property set to `"CSS"`. | `number` | |

## Default Breakpoints

There are six default breakpoints, each corresponding to common device resolutions:

| Breakpoint | Size (pixels) |
|:-|:-|
| `xs` | 320 |
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |
| `2xl` | 1536 |

These values are customizable during component configuration. Refer to [Setup Options](#setup-options).

## Feedback and support

TwicPics Components are open-source on GitHub. For features requests and bugs, [open an issue](https://github.com/TwicPics/components/issues). The TwicPics team also remains available for support via the live chat (at the bottom right.)

---


---

# Integrations

## Akeneo

# Integration with Akeneo

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

## Introduction

### What is TwicPics?

TwicPics is a real-time media processing service that enables developers and companies of all sizes to deliver rich and optimized visual content to their website.

TwicPics is more precisely a Responsive Image Service Solution (SaaS). It offers **on-demand responsive image generation** combined with a **well-thought-out** **and unobtrusive** **JavaScript library**, all based around a **URL-based API**.

### Akeneo Integration

Depending on your Akeneo version, TwicPics provides you with :

- [TwicPics Akeneo App](https://apps.akeneo.com/apps/twicpics-app) for an immediate integration of your PIM assets.
- [TwicPics Akeneo Connector](https://apps.akeneo.com/extension/akeneo-image-cdn-twicpics) which allows to define your PIM as the source of your assets.

<doc-alert type=warning>We strongly recommend the use of the **TwicPics Akeneo App**. It allows you to integrate Akeneo almost immediately.</doc-alert>

In both cases, assets from your PIM will be optimized and served by TwicPics in your websites and applications.

<illustration src="docs/akeneo-twicpics-integration.png" width="2806" height="1464" alt="Akeneo Connection with TwicPics"></illustration>

_Want to know more about TwicPics? Click [here](https://www.twicpics.com/docs/getting-started/why-twicpics) for more information._

### Requirements

Integration between Akeneo and TwicPics requires you to:

- Own an account (PIM) on Akeneo
- Own an account on TwicPics

<doc-alert>The creation of your TwicPics account should be done once the application is connected to your PIM.</doc-alert>

### Supported image types

Depending on your Akeneo edition, you can get and optimize these following image types from your Akeneo PIM to your websites and apps:

#### All editions

- The media files associated to **Products** (see Akeneo [Product Media File documentation](https://api.akeneo.com/api-reference.html#get_media_files__code__download))

#### Enterprise Editions only

- The media files associated to **Assets** (see Akeneo [Asset Media File documentation](https://api.akeneo.com/api-reference.html#get_asset_media_files__code))
- The media files associated to **Reference Entities** or **Records** (see Akeneo [Reference Entities documentation](https://api.akeneo.com/api-reference.html#get_reference_entity_media_files__code))

## Features & benefits

The Akeneo TwicPics App and the Image Optimization Akeneo Connector for TwicPics allow you to benefit from the same features as if you were using TwicPics in the standard way.

- **Media resizing and DPR:** TwicPics automatically detects the DPR of your visitors. It means we automatically size your existing and future images and videos at the correct DPR for any device.
- **Video Optimization**: TwicPics videos are short, muted, auto-playing native HTML video elements. They enable integration of hero, product, and thumbnail videos. [Refer to our documentation to learn to implement video optimization](https://www.twicpics.com/docs/guides/video-optimization).
- **Lazy loading**: TwicPics automatically defers offscreen media to improve page loading time. It also offers images and videos placeholders functionality to deliver a better user experience.
- **Many image formats processing**: TwicPics supports non-animated AVIF, GIF, HEIF, JPEG, PNG and WebP formats for images, and can optimize any source video files up to 30 seconds, 30 FPS, 36 million pixels, 36MB.
- **Next-Gen format conversion**: by default, and for better optimization, TwicPics automatically converts your medias to Next-Gen formats (WebP, WebM, etc.) for all compatible devices.
- **Lossless compression**: TwicPics automatically removes useless data and compresses images and videos on the fly. Reduce image size by up to 75% without compromising its quality.
- **Global CDN**: serve your media closer to your users thanks to a worldwide CDN powered by Amazon™.
- **Rock solid architecture**: 99.999% service uptime and 99.99% image delivery success on average.
- **SEO optimizations**

## Using Akeneo TwicPics App

### Connect your PIM with Akeneo TwicPics App

1. From your Akeneo PIM interface, click on **Connect** page.
2. Click on **App Store**.
3. Search for **TwicPics** in the **APPS** section.
   <illustration src="docs/akeneo-pim-store-red.png" width="3667" height="1966" alt="Find TwicPics App in the Akeneo Store" caption="Find TwicPics App in the Akeneo Store"></illustration>
4. Click on **Connect** button: you will be redirected to TwicPics SignUp page, after going through the Akeneo authorization process.
   <illustration src="docs/akeneo-app-install-1.png" width="3064" height="1620" alt="Authorize TwicPics Akeneo App" caption="Authorize TwicPics Akeneo App"></illustration>
   <illustration src="docs/akeneo-app-install-3.png" width="3062" height="1620" alt="Check all sections" caption="Check all sections"></illustration>
5. Create your TwicPics account.
   <illustration src="docs/akeneo-app-twicpics-signup.png" width="2882" height="1632" alt="Create your TwicPics account" caption="Create your TwicPics account"></illustration>

That's it. Your TwicPics account is now set up and ready to use.

<illustration src="docs/integrations/akeneo/akeneo-app-welcome.png" width="2880" height="1642" alt="Your first workspace" caption="Your dashboard and its first Akeneo workspace"></illustration>

Your first Akeneo workspace is automatically added to your favorites list. Click to open it.

<illustration src="docs/integrations/akeneo/akeneo-app-workspace.png" width="2880" height="1642" alt="Your first Akeneo worskpace" caption="Your worskpace and its first Akeneo domain"></illustration>

Here is your workspace ready to use. It contains a first domain that we have also added to your favorites list. Click to open it and discover your first Akeneo path.

<illustration src="docs/integrations/akeneo/akeneo-app-domain.png" width="2880" height="1642" alt="Your first Akeneo domain" caption="Your domain my-company-akeneo.twic.pics and its first path" ></illustration>

Your first path is operational. Optionally, you can modify its behavior by clicking on the _3-dot icon_ button (add a watermark, a default transformation, etc.)

You can now start [distributing your assets](#integrate-your-pim-images) in your websites and applications from your brand new domain `https://my-company-akeneo.twic.pics`, with `my.company.cloud.akeneo.com` being the name of your PIM.

Feel free to rename the automatically created workspace and domain.

<doc-alert>If you already have a TwicPics account, [contact us](https://www.twicpics.com/contact) once the application is connected. We'll take care of configuring your existing account.</doc-alert>

### TwicPics Akeneo domains

In your `my company akeneo` workspace, in addition to the classic TwicPics domains, you can create **Akeneo domains** which will be automatically associated with your PIM. They are identified by the Akeneo logo <akeneo-logo></akeneo-logo>.

<illustration src="docs/integrations/akeneo/akeneo-app-domain-create.png" width="2880" height="1642" alt="Akeneo Connection with TwicPics" caption="Adding a new domain"></illustration>

All TwicPics paths you create in an Akeneo domain are automatically configured with your Akeneo PIM domain as the _Source URL_ and are ready to use.

From now on, you can begin integrating and optimizing your Akeneo PIM images to your websites and apps with TwicPics.

## Using Akeneo Image CDN by TwicPics

<doc-alert type=warning>If your PIM is compatible with the **TwicPics Akeneo App**, we strongly recommend that you use it.</doc-alert>

The Image Optimization Akeneo Connector for TwicPics works with the Akeneo **1.7+** and **Serenity** versions, depending on which image types you need to request from your Akeneo PIM.

<doc-alert>For now and by default, the option of using Akeneo as a source authentication for image optimization does not appear on the TwicPics back-office. After [creating your TwicPics account](https://account.twicpics.com/signup), contact us to activate the option in your TwicPics back office.</doc-alert>

### Akeneo PIM setup

The very first step to install the Image Optimization Akeneo Connector for TwicPics is to create a _"connection"_ from your PIM interface. [Refer to the complete documentation of Akeneo](https://help.akeneo.com/pim/serenity/articles/manage-your-connections.html) to see how you can create the _"connection"_ that will connect TwicPics to your Akeneo PIM, or apply these following steps:

1. From your Akeneo PIM interface, click on **Connect**.
2. Then on **Connection** settings.
3. Click on the button **Create** that will redirect you to the _"connection"_ creation form.
4. Here in the _Label_ field, enter the name of the connector - this name could be _TwicPics_ or _TwicPics connector_.
5. Choose the _Flow type_ of your _"connection"_ (see [the official documentation](https://help.akeneo.com/pim/serenity/articles/manage-your-connections.html#choose-your-flow-type) for more information).
6. Grab your _"connection"_ credentials (**Client Id**, **Secret**, **Username** and **Password**). Through the header `authentication` of the connector, they will be used to authenticate TwicPics' calls to Akeneo API and get your images from your PIM.
   <illustration src="docs/akeneo-connector-2.png" width="1068" height="685" alt="TwicPics domain screenshot"></illustration>

7. Set the proper permissions for both the _user role_ and the _user group_ (see [the official documentation](https://help.akeneo.com/pim/serenity/articles/manage-your-connections.html#set-the-permissions) for more information).

### TwicPics account setup

#### Create your TwicPics account

If you don't have any TwicPics account yet, you can easily [sign up here for free](https://account.twicpics.com/signup).

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

<illustration src="docs/akeneo-connector-2-3.png" width="2870" height="1138" alt="TwicPics domain screenshot"></illustration>

#### Connect your TwicPics domain to your Akeneo PIM

From the "**Domains**" section of your TwicPics **Workspace**, click on the _Create path_ button.

A panel will open, in which you must set the URL of your Akeneo PIM as the _Source URL_.

For instance, if your Akeneo PIM is located at `https://<your-pim-subdomain>.akeneo.com` then the _Source URL_ must be set to `https://<your-pim-subdomain>.akeneo.com`.

<illustration src="docs/akeneo-connector-2-4.png" width="2870" height="1388" alt="TwicPics domain screenshot"></illustration>

Then, select the _Akeneo Connector_ option as the source authentication to fetch your images from your Akeneo PIM.

<illustration src="docs/akeneo-connector-2-5.png" width="2870" height="1126" alt="TwicPics domain screenshot"></illustration>

And fill in the credentials of your TwicPics connector (grabbed from your Akeneo PIM) in the dedicated fields.

<illustration src="docs/akeneo-connector-2-6.png" width="2868" height="1140" alt="TwicPics domain screenshot"></illustration>

Click on the _Add_ button located at the bottom right of the popup window: the newly created connection between your TwicPics domain and your Akeneo PIM now appears in the list of paths.

From now on, you can begin integrating and optimizing your Akeneo PIM images to your websites and apps with TwicPics.

## Integrate your PIM images

To integrate and optimize your Akeneo PIM images with TwicPics, simply use your TwicPics domain (e.g. `https://my-company-akeneo.twic.pics`).
The endpoint to use depends on the type of image to be optimized:

### By assets media files

- Endpoint: `/media/<file path>`, with `<file path>` being the media file associated to an asset.
- For instance: `https://my-company-akeneo.twic.pics/media/<file path>` could be `https://my-company-akeneo.twic.pics/media/5/9/z/2/59z243z8b1586_DEMO_IMAGE.jpg`.

### By products media files

- Endpoint: `/product/<file path>`, with `<file path>` being the media file associated to a product.
- For instance: `https://my-company-akeneo.twic.pics/product/<file path>` could be `https://my-company-akeneo.twic.pics/product/5/9/z/2/59z243z8b1586_DEMO_IMAGE.jpg`.

### By categories media files

- Endpoint: `/category/<file path>`, with `<file path>` being the media file associated to a category.
- For instance: `https://my-company-akeneo.twic.pics/category/<file path>` could be `https://my-company-akeneo.twic.pics/category/5/9/z/2/59z243z8b1586_DEMO_IMAGE.jpg`.

### By assets media files of a given asset family

Available for _**Akeneo Enterprise Editions only**_.

- Endpoint: `/asset/<asset family>/<media code>`, with `<media code>` being the code of the media file associated to an asset, and `<asset family>` the name of the asset family it belongs to.
  <doc-alert type="warning">Due to the behavior of Akeneo API, you have to indicate the name of the asset family to get the asset media file.</doc-alert>
- For instance: `https://my-company-akeneo.twic.pics/asset/<asset family>/<media code>` could be `https://my-company-akeneo.twic.pics/asset/deco/DECO_TEXTILE_CURTAIN_WHITE_300152243027`.

### By reference entities or records media files

Available for _**Akeneo Enterprise Editions only**_.

- Endpoint: `/reference-entity/<media code>` with `<media code>` being the code of the media file associated to a reference entity or a record.
- For instance: `https://my-company-akeneo.twic.pics/reference-entity/<media code>` could be `https://my-company-akeneo.twic.pics/reference-entity/color200`.

<doc-alert>To integrate your images on your websites and apps, you can either use the TwicPics Native to automatically adapt your PIM images to your users or the API if you prefer writing manual request optimizations.</doc-alert>

The example below shows a PIM image integration with TwicPics Native:

```html
<img
  data-twic-src="image:media/5/9/z/2/59z243z8b1586_DEMO_IMAGE.jpg"
  alt="Demo image"
/>
```

<doc-alert>You can refer to our documentation for more information about [TwicPics Native setup](https://www.twicpics.com/docs/essentials/native).</doc-alert>

Here the example makes use of TwicPics API to integrate the PIM image:

```html
<img
  src="https://my-company-akeneo.twic.pics/media/5/9/z/2/59z243z8b1586_DEMO_IMAGE.jpg?twic=v1/cover=16:9/resize=600"
  alt="Demo image"
/>
```

<doc-alert>Refer to our [API documentation](https://www.twicpics.com/docs/reference/transformations) to see every possible transformation you can manually apply to your Akeneo PIM images.</doc-alert>

## Select specific assets media files

The assets media files endpoint can actually feature multiple images. By default, the TwicPics Akeneo Connector will use the first one following the order in which the Akeneo API itself sent them.

You can override this behaviour in two ways:

- using _indexing_
- using _filtering_

### Indexing

Let's consider the asset located at `https://my-company-akeneo.twic.pics/asset/cloth/dress` and let's suppose that there are at least three images associated to it.

You can retrieve the third image by adding its index at the end of the URL like so:

`https://my-company-akeneo.twic.pics/asset/cloth/dress/2` (notice the `/2` at the end)

Indexes are _zero-based_, thus to get the first element, you have to use index `0` and to get the third element, you have to use index `2`.

If the asset only features two images, then the TwicPics Akeneo Connector will simply circle back. So, in that instance, the three following URLs would be strictly equivalent:

- `https://my-company-akeneo.twic.pics/asset/cloth/dress/2`
- `https://my-company-akeneo.twic.pics/asset/cloth/dress/0`
- `https://my-company-akeneo.twic.pics/asset/cloth/dress`

### Filtering

While indexing can be useful, it can prove more effective to filter images based on associated values.

Many asset media are localized and this information is usually stored in the Akeneo API as a `locale` value attached to each image. You can add a filtering condition at the end of the URL to select language-specific images.

For instance:

`https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US`

would retrieve the american english images associated with the asset.

If there happen to be several such images, you can use indexing to select a specific one like so:

`https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US/1`

But what happens if you don't have a `locale=en_US` image? The TwicPics Akeneo Connector would return a `404` response. Thankfully, you can chain filters so that each subsequent filter acts as a fallback.

Let's take the following example:

`https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US/locale=fr_FR/locale=null`.

This will deliver:

- the first american english image if there is any
- failing that, the first french image if there is any
- failing that, the first non-language specific image is there is any

Furthermore, filters can contain complex logical expressions using parenthesis and logical operators `&` and `|`.

For instance, supposing you have a `color` value associated to your images, you could write filters of the form:

- `locale=en_US&color=blue`
- or `(locale=en_US|locale=fr_FR)&color=blue`

Finally, the special filter `true` can be useful as a _"whatever is there"_ kind of fallback.

For instance, `locale=en_US&color=blue/true` would return the american english, blue colored images if they exist or _whatever is there_ otherwise.

## Support service

For any issue related to the Image Optimization Akeneo Connector for TwicPics, please contact the support team by sending an email at <support@twic.pics>.

Check out our [Service Level Agreement](https://www.twicpics.com/legal/service-level-and-support) to get more information about our different services.

---

## WordPress

# WordPress Plugin Set Up

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

## Set up your TwicPics domain

### Create your TwicPics account

If you don't have one, you can easily [create your account](https://account.twicpics.com/signup) for free.

### Create your TwicPics domain

Then set your personal TwicPics **domain** (e.g. `xxxxxx.twic.pics`). This step is necessary to optimize your images, as they will be delivered through your TwicPics domain.

### Connect your TwicPics domain to your WordPress website

Apply the following steps to connect your TwicPics domain to your WordPress website.

<doc-alert>These manual operations will be automated in future versions of the plugin.</doc-alert>

1. Select your workspace from the **Workspace** section.
   <illustration src="docs/integrations/wordpress/screenshot-1.png" width="2880" height="1716" alt="dd"></illustration>
2. Then go to the **Domains** section, select your domain, and click on the _Create path_ button.
   <illustration src="docs/integrations/wordpress/screenshot-2.png" width="2880" height="1716" alt="dd"></illustration>
   <illustration src="docs/integrations/wordpress/screenshot-3.png" width="2880" height="1716" alt="dd"></illustration>
   <illustration src="docs/integrations/wordpress/screenshot-4.png" width="2880" height="1716" alt="dd"></illustration>
3. A panel opens, in which you **must set both** _Path_ and _Source URL_ to the URL of your WordPress website. For instance, if your WordPress website is located at `https://www.my-website.com`, then _Path_ should be set to `https://www.my-website.com` and _Source URL_ should also be set to `https://www.my-website.com`.
   <doc-alert type="warning">The Plugin does not support video optimization yet: please select `Images` for _Type of media_.</doc-alert>
   <illustration src="docs/integrations/wordpress/screenshot-5.png" width="2880" height="1716" alt="dd"></illustration>
4. Finally, click on the _Save path_ button, located at the bottom right of the panel window. The new path appears in the list of your domain paths.

<doc-alert>To check if everything was set up properly, find the URL of an image on your WordPress website, prepend `https://<subdomain>.twic.pics/` to it (with `<subdomain>` being your _actual_ subdomain), enter the result in your browser address bar and your image should appear.<br/><br/>
For instance if the URL of the image on your WordPress website is `https://www.my-website.com/wp-content/uploads/picture.jpg`, then entering `https://<subdomain>.twic.pics/https://www.my-website.com/wp-content/uploads/picture.jpg` (with `<subdomain>` being your _actual_ subdomain) in your browser address bar should display the image.<br/><br/>
If it does not work, try to retrace your steps. If you still can't figure out what went wrong, feel free to contact us using the chat box on the bottom right of this very page.</doc-alert>

<doc-alert>If you have multiple WordPress websites, just repeat the operation for each of them. A TwicPics domain can hold as many paths as necessary.</doc-alert>

<doc-alert type="info">
Read more about <nuxt-link to="/docs/essentials/path-configuration">paths configuration</nuxt-link>.
</doc-alert>

Keep the TwicPics back-office open or copy your TwicPics domain name somewhere: you'll need it to configure the Plugin in your WordPress admin area.

## Install the Plugin

Install the [TwicPics Plugin](https://wordpress.org/plugins/twicpics/) just like you would do with any other WordPress plugin.

## Plugin Settings

<doc-alert type="warning">If you have any other image optimization plugin or any lazy-loading plugin installed, please disable them before moving forward.</doc-alert>

In your WordPress admin area:

1. Navigate to your WordPress plugins page and activate the TwicPics Plugin.
2. Navigate to the TwicPics Plugin settings (there is a link at the top level of your WordPress admin menu and in the _Media_ submenu).
3. Fill in the **TwicPics domain** field with your TwicPics domain.
4. Select the **Optimization level** that will be applied to your images:

   - Pixel perfect (default): JavaScript based, pixel-perfect, lazy loaded image replacement.
   - Maximum compatibility: static, purely HTML based image replacement.
     <doc-alert>The default approach should work 90% of the time but some plugins and/or themes, especially JavaScript-heavy ones, may clash with it. Use _Maximum compatibility_ if and when you witness weird image distortions and/or flickering.</doc-alert>

5. Click on the _Save Settings_ button.

<illustration src="docs/integrations/wordpress/screenshot-6.png" width="2880" height="2624" alt="TwicPics Plugin settings"></illustration>

Congratulations! You just have enabled image optimization by TwicPics on your WordPress website.

## Advanced Settings

<doc-alert type="warning">We recommand not to mess with advanced settings unless you know exactly what you are doing.</doc-alert>

### Max width of images

Maximum intrinsic width of images in pixels. This prevents generating insanely large images on very wide screens.

_Default value_: `2000`

<doc-alert type="warning">Using a lower value than the default could severely decrease the quality of the images on your WordPress website.</doc-alert>

### Resize step

Numbers of pixels image width is rounded by.

**Only available with the _Pixel perfect_ optimization level.**

_Default value_: `10`

This will reduce the number of variants generated and help CDN performance.  
With the default of `10`, a `342` pixel-wide image will be rounded down to `340` pixels.

<doc-alert type="warning">The higher the step, the less pixel perfect the result, so use with caution.</doc-alert>

### Placeholder type

Image placeholder (LQIP) displayed while image is loading.

**Only available with the _Pixel perfect_ optimization level.**

- Blank (default): nothing.
- Main color: the most represented color in the image
  <img src="https://assets.twic.pics/demo/anchor.jpeg?twic=v1/cover=100x100/output=maincolor" width="100" height="100" alt="dd">
- Mean color: the average color of the image
  <img src="https://assets.twic.pics/demo/anchor.jpeg?twic=v1/cover=100x100/output=meancolor" width="100" height="100" alt="dd">
- Preview: a blurry preview of the image
  <img src="https://assets.twic.pics/demo/anchor.jpeg?twic=v1/cover=100x100/output=preview" width="100" height="100" alt="dd">

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

---