---
title: 'TwicPics Native Attributes'
menuTitle: 'Native Attributes'
description: 'The complete reference of the attributes recognized by TwicPics Native.'
category: 'reference'
position: 1
---

# 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](/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](/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](/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](/docs/reference/transformations#focus-point) for transformations. The value of this attribute must be `none` or, like in [the focus API](/docs/reference/transformations#focus), valid [coordinates](/docs/reference/parameters#coordinates), an [anchor](/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](/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`](/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`](/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](/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"
/>
```