TwicPics Native Attributes

The complete reference of the attributes recognized by TwicPics Native.

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.

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

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

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

The attribute also accepts placeholder expressions.

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

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

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

<!-- 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

You'll seldom need to use modifier attributes (with the notable exception of data-twic-bot and 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.

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 when search engine bots are crawling your page and it supports the exact same syntax.

When used with an empty value, the default transformations will be applied.

Search engines detected include, amongst others:

If absent, 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.

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

Note that data-twic-focus and data-twic-step will still be used for when search engine bots are visiting.

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.

<!-- 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 for transformations. The value of this attribute must be none or, like in the focus API, valid coordinates, an anchor or auto.

<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>
Note that, for multiple backgrounds, it is possible to specify multiple focuses.
Videos do not support focus focus="auto" yet.

data-twic-intrinsic

Default value: none

Specifies the intrinsic dimensions of the image. It's a pixel 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)
<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-transformdata-twic-intrinsic
none or *1000x1500
crop=50p/*500x1500
*/resize=50p1000x1500
cover=500x500not taken into account
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.

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 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 for more details).

Note that to maximize cache effiencicy, the default step for videos is set to 100. Any values below will be ignored.
<!-- 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>
Note that, for multiple backgrounds, it is possible to specify multiple steps.

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.

<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>
Note that, for multiple backgrounds, it is possible to specify multiple transforms.

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.

<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>
Please note those values are rounded by default (see data-twic-step ).

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.

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

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

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

GenericSourcePosterBackground
data-twic-botdata-twic-src-botdata-twic-poster-botdata-twic-background-bot
data-twic-focusdata-twic-src-focusdata-twic-poster-focusdata-twic-background-focus
data-twic-intrinsicdata-twic-src-intrinsicdata-twic-poster-intrinsicdata-twic-background-intrinsic
data-twic-stepdata-twic-src-stepdata-twic-poster-stepdata-twic-background-step
data-twic-transformdata-twic-src-transformdata-twic-poster-transformdata-twic-background-transform
In case both the generic modifier attribute and the medium-specific modifier attribute are set, the latter takes precedence over the former.
<!-- focus for source is "auto", not "25px53p" -->
<img
  data-twic-src="image:picture.jpeg"
  data-twic-focus="25px53p"
  data-twic-src-focus="auto"
/>
responsive images

The All-In-One Toolbox For Your Medias

The simplest, most powerful way to tackle responsive images & videos