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

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.

Search engines detected include, amongst others:

• Google
• Bing
• Yahoo
• DuckDuckGo
• Baidu
• Yandex
• Sogou
• Exalead

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.

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>

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

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

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>

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>

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:

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