ember-cli-imgix
Advanced tools
An Ember addon for easily adding responsive imagery via imgix to your application.
ember-cli-imgix is an add-on that provides custom components for integrating imgix into Ember sites.
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.
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:
srcset and imgix. A look into how imgix can work with srcset and sizes to serve the right image.From within an existing ember-cli project:
ember install ember-cli-imgix
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
};
};
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:
{{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)
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
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
)
}}
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 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.
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.
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.
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.
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:
// config/environment.js
module.exports = function(environment) {
var ENV = {
// snip
APP: {
imgix: {
// snip
disableLibraryParam: true
}
}
// snip
};
};
{{imgix-image path="/test.png" disableLibraryParam={true} }}
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 is available to you shimmed as:
import imgix from '@imgix/js-core';
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.
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.
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). If sizes is new to you (or even if it's not), Eric's seminal article on srcset and sizes is highly recommended.aspectRatio has been moved to options.ar. Thus, aspectRatio has been deprecated. It will be supported until the v3 release. The format of the new options.ar attribute is w:h.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.
srcset, sizes, or picture will gracefully fall back to the default img src when appropriate. If you want to provide a fully-responsive experience for these browsers, ember-cli-imgix works great alongside Picturefill!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.
Pretty simple:
ember test
FAQs
An Ember addon for easily adding responsive imagery via imgix to your application.
We found that ember-cli-imgix demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.