Script Attributes

The Script handles 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>">

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

The attribute also accepts placeholder expressions.

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

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>)">

The Script 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 ). Styling elements with CSS will suffice most of time, especially given the Script 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 Google and Bing search 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.

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 the Script 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>

In the example above, while regular visitors will receive different variants depending on their browsing context, Google and Bing search 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-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 or auto.

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

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

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 step script 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 script parameter documentation for more details).

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

data-twic-transform

Default value: *

Specifies the manipulation to be applied to the medium. The attribute accepts the full manipulation 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>
Note that, for multiple backgrounds, it is possible to specify multiple transforms.

As an addition, the Script 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>
Please note those values are rounded by default (see data-twic-step ).

As a convenience, the Script 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>

The Script also provides an additional transformation which is used by default: *. What this transformation does depends on the value of the object-fit or background-size CSS property for the current image 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>

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>

Medium-specific modifier attributes

While data-twic-bot, data-twic-focus, 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-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 Images

The simplest, most powerful way to tackle responsive images.