ember-cli-imgix

An Ember addon for easily adding responsive imagery via imgix to your application. This addons supports FastBoot.

Note: Front-end imgix libraries and framework integrations will not work with imgix Web Proxy Sources. They will only work with imgix Web Folder or S3 Sources.

Installation

From within an existing ember-cli project:

$ ember install ember-cli-imgix

Next, set up some configuration flags:

// config/environment.js

module.exports = function(environment) {
  var ENV = {
    // snip
    APP: {
      imgix: {
        source: 'my-social-network.imgix.net',
        debug: true // Prints out diagnostic information on the image itself. Turn off in production.
      }
    }
    // snip
  };
};

Usage

NOTE: These docs are for the latest version of ember-cli-imgix (version 1). For the old docs, please go here

imgix-image

ember-cli-imgix exposes a img element with expanded functionality. It simply renders an img, but has some extra parameters

{{imgix-image path='/users/1.png'}}

Which will generate some HTML similar to this:

<img class="imgix-image" src="https://my-social-network.com/users/1.png?w=400&h=300&dpr=1" >

The src attribute will have imgix URL API parameters added to it to perform the resize.

Note: This element works by calculating the width/height from its parent. If its parent has no width/height, then this component will do nothing.

Parameters

You can pass through most of the params that imgix urls accept.

Some of the defaults are:

path: null, // The path to your image
aspectRatio: null,
crop: null,
fit: 'crop',
pixelStep: 10, // round to the nearest pixelStep
onLoad: null,
onError: null,
crossorigin: 'anonymous', // img element crossorigin attr
alt: '', // img element alt attr
draggable: true, // img element draggable attr
options: {}, // arbitrary imgix options
auto: null, // https://docs.imgix.com/apis/url/auto

width: null, // override if you want to hardcode a width into the image
height: null, // override if you want to hardcode a height into the image

Other imgix options

If you want to pass in any other arbitrary imgix options, use the hash helper

{{imgix-image
  path='/users/1.png'
  options=(hash
    invert=true
  )
}}

aspectRatio

This component can also accept an aspectRatio parameter:

{{imgix-image-element path="/users/1.png" crossorigin="anonymous" aspectRatio=1.33}}

Lifecycle hooks

This element also exposes onLoad and onError actions which you can hook into to know when the image has loaded or failed to load:

{{imgix-image
  path='/users/1.png'
  onLoad=(action 'handleImageLoad')
  onError=(action 'handleImageError')
}}

This will maintain the same aspect ratio as the image is resized.

Please see the dummy app for insight into setting this up and configuring this.

ixlib param

This library adds an ixlib parameter to generated image urls for two reasons: a) it helps Imgix support see what versions of libraries that customers are using, and b) it help Imgix to see how many people overall are using the ember library, and the specific versions.

If this behaviour is not desired, it can be turned off in two ways:

1. Environment config

// config/environment.js

module.exports = function(environment) {
  var ENV = {
    // snip
    APP: {
      imgix: {
        // snip
        disableLibraryParam: true
      }
    }
    // snip
  };
};

2. Component parameter

{{imgix-image path="/test.png" disableLibraryParam={true} }}

imgix-image-wrapped - DEPRECATED

This component is included to help migration from version 0.x. This component will be deprecated in version 2. Please use imgix-image instead.

ember-cli-imgix exposes a image container that works well for creating responsive images. It is a <div> element with a single <img> child element. Adding them to your templates is quite easy:

{{imgix-image-wrapped path="/users/1.png"}}

The HTML generated by this might look like the following:

<div>
  <img src="https://my-social-network.com/users/1.png?w=400&h=300&dpr=1" />
</div>

The src attribute will have imgix URL API parameters added to it to perform the resize.

Imgix Core JS

Imgix core js is available to you shimmed as:

import ImgixCoreJs from 'imgix-core-js';

Upgrade Guide

version 0.x to version 1

imgix-image has been replaced by a new implementation of imgix-image-element. All usage of imgix-image-element can be replaced with imgix-image. No parameter changes are necessary.

imgix-image has been renamed to imgix-image-wrapped and has been deprecated. All usage of imgix-image can be replaced with imgix-image-wrapped for the duration of version 2. No parameter changes are necessary. After version 2, imgix-image-wrapped will not exist.

Running a test app

To see this in action with some stock photos, clone this repo and then run ember serve

git clone git@github.com:imgix/ember-cli-imgix.git
cd ember-cli-imgix
ember serve

Now visit http://localhost:4200.

Running Tests

Pretty simple:

ember test