Placeholders

The complete reference for the TwicPics placeholders API.

Every manipulation 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`
`resize=150x100/placeholder:rgb(128,0,128)`
`placeholder:200x100:medium-violet-red`

Syntax

A placeholder follows the following syntax: placeholder:[<dimensions>:]<colors>

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.

This alternate URL format is also used internally by TwicPics Native .

Working with absolute URLs for paths

If you used absolute URLs as paths 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.

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`

If not specified, the dimensions of a placeholder default to 1920x1080.

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`

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 to be used for the text and the background of the image respectively.

Example	Result
`placeholder:50x50:white/red`

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.

Example	Result
`placeholder:50x50:orange`
`placeholder:50x50:black`
`placeholder:50x50:auto`

Color chaining

Reference