- Overview / Resources
- Upgrade Guide
- Browser Support
- Running a Test App
- Running Tests
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
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
srcsetand imgix. A look into how imgix can work with
sizesto serve the right image.
From within an existing ember-cli project:
The global configuration for this library should be located in
APP.imgix, and has the following schema:
It should look like this in
NOTE: These docs are for the latest version of
ember-cli-imgix (version 1). For the old docs, please go here
ember-cli-imgix exposes an
img element with expanded functionality:
Which will generate HTML similar to this:
The src attribute will have imgix URL API parameters added to it to perform the resize.
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
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:
NB: Since this library sets
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.
You can pass through most of the params that imgix urls accept.
Some of the defaults are:
Other imgix Options
If you want to pass in any other arbitrary imgix options, use the hash helper
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.
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
attributeNameMap helps with this.
In the global config,
attributeNameMap allows the following to be remapped:
For example, to remap
The equivalent works for
This element also exposes
onError actions which you can hook into to know when the image has loaded or failed to load:
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.
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
sizes by changing some configuration settings:
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
srcset by changing some configuration settings, and providing a fallback image to
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.
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
- Component parameter
This component will render a
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.
This will generate html similar to the following:
imgix-bg will respect any global default parameters unless explicitly overriden.
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
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:
The HTML generated by this might look like the following:
src attribute will have imgix URL API parameters added to it to perform the resize.
imgix-core-js is available to you shimmed as:
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
sizes for responsiveness. This has a host of benefits, including better server rendering, better responsiveness, less potential for bugs, and perfomance improvements.
sizesprop should be added to all usages of ember-cli-imgix, unless the width or height of the image are known beforehand (see above). If
sizesis new to you (or even if it's not), Eric's seminal article on
sizesis highly recommended.
aspectRatiohas been moved to
aspectRatiohas been deprecated. It will be supported until the v3 release. The format of the new
- By default, browsers that don't support
picturewill gracefully fall back to the default
srcwhen appropriate. If you want to provide a fully-responsive experience for these browsers,
ember-cli-imgixworks 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
Now visit http://localhost:4200.
More Framework Libraries
- django-imgixbuildAn app for integrating imgix into Django sitesPython 1 21 days ago
- imgix-railsbuildA gem for integrating imgix into Rails projectsRuby 89 a month ago
- jekyll-imgixbuildA plugin for integrating imgix into Jekyll sitesRuby 46 16 days ago