ember-cli-imgix
v3.0.3
Published
An Ember addon for easily adding responsive imagery via imgix to your application.
Downloads
146
Readme
ember-cli-imgix
is an add-on that provides custom components for integrating imgix into Ember sites.
- Overview / Resources
- Installation
- Usage
- Upgrade Guide
- Browser Support
- Running a Test App
- Running Tests
- License
Note: Front-end imgix libraries and framework integrations will not work with imgix Web Proxy Sources. They will only work with S3, Azure, Google Cloud Storage, or Web Folder sources.
Overview / Resources
Before you get started with ember-cli-imgix
, it's highly recommended that you read Eric Portis' seminal article on srcset
and sizes
. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of ember-cli-imgix
is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your experience when using these components. For a demonstration of this library in action, check out this demo.
Below are some other articles that help explain responsive imagery, and how it can work alongside imgix:
- Responsive Images with
srcset
and imgix. A look into how imgix can work withsrcset
andsizes
to serve the right image.
Installation
From within an existing ember-cli project:
ember install ember-cli-imgix
Global Configuration
The global configuration for this library should be located in APP.imgix
, and has the following schema:
imgix: {
source: string,
debug?: boolean,
attributeNameMap?: {
src: string
srcset: string
sizes: string
},
classNames?: string,
defaultParams?: {}
}
It should look like this in config/environment.js
.
// 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.
classNames: 'imgix-image', // default class used on the img element
defaultParams: {}, // optional params that will be used in all generated paths
}
}
// 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 an img
element with expanded functionality:
{{imgix-image path='/users/1.png' sizes='100vw'}}
Which will generate HTML similar to this:
<img
class="imgix-image"
src="https://my-social-network.com/users/1.png"
sizes="100vw"
srcset="https://my-social-network.com/users/1.png?w=100 100w, https://my-social-network.com/users/1.png?w=200 200w, ..."
/>
The src attribute will have imgix URL API parameters added to it to perform the resize.
Please note: 100vw
is an appropriate sizes
value for a full-bleed image. If your image is not full-bleed, you should use a different value for sizes
. Eric Portis' "Srcset and sizes" article goes into depth on how to use the sizes
attribute.
Since imgix can generate as many derivative resolutions as needed, ember-cli-imgix
calculates them programmatically, using the dimensions you specify. All of this information has been placed into the srcset and sizes attributes.
Width and height known: If the width and height are known beforehand, it is recommended that they are set explicitly:
{{imgix-image path='/users/1.png' width=100 height=100}}
NB: Since this library sets fit
to crop
by default, when just a width or height is set, the image will resize and maintain aspect ratio. When both are set, the image will be cropped to that size, maintaining pixel aspect ratio (i.e. edges are clipped in order to not stretch the photo). If this isn't desired, set fit
to be another value (e.g. clip
)
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
crop: null,
fit: 'crop',
onLoad: null,
onError: null,
crossorigin: 'anonymous', // img element crossorigin attr
alt: '', // img element alt attr
draggable: true, // img element draggable attr
disableSrcSet: false, // disable srcSet generation
options: {}, // arbitrary imgix options
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
)
}}
Aspect Ratio
This component can also accept an ar
parameter to constrain the aspect ratio of the returned image. The aspect ratio is specified in the format width:height. Either dimension can be an integer or a float. All of the following are valid: 16:9, 5:1, 1.92:1, 1:1.67.
{{imgix-image path="/users/1.png" crossorigin="anonymous" options=(hash ar="1.33:1"}}
attributeNameMap
attributeNameMap
should be used if it is required to remap the HTML attribute to be used to set the src of the image. For example, if data-src
should be used rather than src
, attributeNameMap
helps with this.
In the global config, attributeNameMap
allows the following to be remapped: src
, srcset
, and sizes
.
For example, to remap srcset
to data-srcset
:
attributeNameMap: {
srcset: `data-srcset`
}
The equivalent works for src
and sizes
.
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.
Lazy Loading
If you'd like to lazy load images, we recommend using lazysizes. In order to use ember-cli-imgix
with lazysizes generate the component with lazysizes-compatible attributes instead of the standard src
, srcset
, and sizes
by changing some configuration settings:
// config/environment.js
module.exports = function(environment) {
var ENV = {
// snip
APP: {
imgix: {
attributeNameMap: {
src: 'data-src',
srcset: 'data-srcset'
}
}
}
// snip
};
};
Otherwise, you can use the component as normal.
NB: It is recommended to use the attribute change plugin in order to capture changes in the data-* attributes. Without this, changing the attributes to this library will have no effect on the rendered image.
Low Quality Image Placeholder Technique (LQIP)
If you'd like to use LQIP images, we recommend using lazysizes. In order to use ember-cli-imgix
with lazysizes, generate the component with lazysizes-compatible attributes instead of the standard src
and srcset
by changing some configuration settings, and providing a fallback image to placeholderPath
.
// config/environment.js
module.exports = function(environment) {
var ENV = {
// snip
APP: {
imgix: {
attributeNameMap: {
src: 'data-src',
srcset: 'data-srcset'
}
}
}
// snip
};
};
// usage
{{imgix-image path='/abc.png' placeholderPath='/abc.png?w=80&h=50' }}
NB: If the props of the image are changed after the first load, the low quality image will replace the high quality image. In this case, the src
attribute may have to be set by modifying the DOM directly, or the lazysizes API may have to be called manually after the props are changed. In any case, this behaviour is not supported by the maintainers of ember-cli-imgix
, so use at your own risk.
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:
- Environment config
// config/environment.js
module.exports = function(environment) {
var ENV = {
// snip
APP: {
imgix: {
// snip
disableLibraryParam: true
}
}
// snip
};
};
- Component parameter
{{imgix-image path="/test.png" disableLibraryParam={true} }}
imgix-bg
This component will render a div
whose background-image
is set to the given image path. Content can be added within the imgix-bg
tags and the component will automatically resize to fit around it.
{{#imgix-bg path='/users/1.png' }}
Some content here
{{/imgix-bg}}
This will generate html similar to the following:
<div style="background-image: url('https://my-social-network.com/users/1.png?fit=crop&w=1246&h=15&dpr=2&ixlib=ember-2.0.0');background-size: cover" class="imgix-bg">
Some content here
</div>
Note: imgix-bg
will respect any global default parameters unless explicitly overriden.
@imgix/js-core
@imgix/js-core
is available to you shimmed as:
import imgix from '@imgix/js-core';
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.
version 1.x to version 2.x
The largest change in this major version bump is the move to width-based srcSet
and sizes
for responsiveness. This has a host of benefits, including better server rendering, better responsiveness, less potential for bugs, and perfomance improvements.
- A
sizes
prop should be added to all usages of ember-cli-imgix, unless the width or height of the image are known beforehand (see above). Ifsizes
is new to you (or even if it's not), Eric's seminal article onsrcset
andsizes
is highly recommended. aspectRatio
has been moved tooptions.ar
. Thus,aspectRatio
has been deprecated. It will be supported until the v3 release. The format of the newoptions.ar
attribute isw:h
.
version 2.x to version 3.x
The largest change in this major version is that the imgix-image-wrapped
component has been removed and we've upgraded the base Ember CLI blueprint to the latest. This version should also work with applications using Embroider.
Browser Support
- By default, browsers that don't support
srcset
,sizes
, orpicture
will gracefully fall back to the defaultimg
src
when appropriate. If you want to provide a fully-responsive experience for these browsers,ember-cli-imgix
works great alongside Picturefill! - We support the latest version of Google Chrome (which automatically updates whenever it detects that a new version of the browser is available). We also support the current and previous major releases of desktop Firefox, Internet Explorer, and Safari on a rolling basis. Mobile support is tested on the most recent minor version of the current and previous major release for the default browser on iOS and Android (e.g., iOS 9.2 and 8.4). Each time a new version is released, we begin supporting that version and stop supporting the third most recent version.
Running a Test App
To see this in action with some stock photos, clone this repo and then run ember serve
git clone [email protected]:imgix/ember-cli-imgix.git
cd ember-cli-imgix
ember serve
Now visit http://localhost:4200.
Running Tests
Pretty simple:
ember test