imgix

imgix-statamic

imgix

imgix logo

imgix-statamic is an add-on for integrating imgix into Statamic sites.

Statamic Version Build Status License


Please note that the base branch of imgix-statamic is designed for Statamic v2.x and that we are no longer actively developing for Statamic v1.x. If you are using Statmic v1.x, take a peek at the version 1 branch.

Installation

  1. Copy site/addons/imgix into your Statamic installation's site/addons folder. Source can be downloaded from the Statamic Marketplace.
  2. Copy site/settings/addons/imgix.yaml into your Statamic installation's site/settings/addons folder.
  3. Configure imgix.yaml:
    • source (Required): The imgix source domain to grab images from.
    • secure_url_token: Add this if you want to output signed (secure) image URLs.
    • use_https: Whether to use HTTPS URLs.
    • responsive_resolutions: The device pixel ratios used to generate srcset attributes.
  4. Run please addons:refresh to install dependencies.

Usage

After you've installed and configured imgix-statamic, you can start using it in your Statamic templates! You can use any available imgix parameter, including face detection, automatic format detection (e.g. WebP), and more. Here are some examples to get you started:

imgix:image_tag

imgix:image_tag allows users to generate <img> elements quickly with the option of appending imgix parameters to the image source.

{{ imgix:image_tag path="dogs.png" w="200" rot="10" alt="Some dogs!" }}

Will output the following HTML:

<img src="https://your-source.imgix.net/dogs.png?w=200&rot=10" alt="Some dogs!">

imgix:image_url

imgix:image_url allows users to construct image URLs quickly with the option of appending imgix parameters.

{{ imgix:image_url path="dogs.png" w="200" }}

Will output the following URL:

https://your-source.imgix.net/dogs.png?w=200

imgix:responsive_image_tag

imgix:responsive_image_tag will generate an img element with a filled-out srcset attribute that leans on imgix to do the hard work. It uses the configured device pixel ratios in the responsive_resolutions config variable (which defaults to [1, 2]). We talk a bit about using the srcset attribute in an application in the following blog post: “Responsive Images with srcset and imgix”.

{{ imgix:responsive_image_tag path="dogs.png" w="200" }}

Will output the following HTML:

<img srcset="https://your-source.imgix.net/dogs.png?w=200 1x,
             https://your-source.imgix.net/dogs.png?w=200&dpr=2 2x"
     src="https://your-source.imgix.net/dogs.png?w=200">

imgix:picture_tag

imgix:picture_tag will generate a <picture> element with a single source element and a fallback img element. It uses the configured device pixel ratios in the responsive_resolutions config variable (which defaults to [1, 2]).

{{ imgix:picture_tag path="dogs.png" w="200" alt="Some dogs!" }}

Will output the following HTML:

<picture>
    <source srcset="https://your-source.imgix.net/dogs.png?w=200 1x,
                    https://your-source.imgix.net/dogs.png?w=200&dpr=2 2x">
    <img src="https://your-source.imgix.net/dogs.png?w=200" alt="Some dogs!">
</picture>

Pass-through Attributes

Any imgix method that generates an img tag (image_tag, responsive_image_tag, and picture_tag) will automatically pass through the following attributes to the tag, if provided:

  • alt
  • longdesc
  • title
  • data-*
  • aria-*

Meta

imgix-statamic was made by imgix. It's licensed under the BSD 2-Clause license (see the license file for more info).