You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Responsive images in the browser, simplified. Pure JavaScript with zero dependencies. About 2 KB minified and gzipped.
6
+
7
+
*[Overview / Resources](#overview-and-resources)
8
+
*[Installation](#installation)
9
+
*[Usage](#usage)
10
+
*[`ix-src`](#ix-src)
11
+
*[`ix-path` and `ix-params`](#ix-path-and-ix-params)
12
+
*[`picture` tags](#picture-tags)
13
+
*[Browser Support](#browser-support)
14
+
*[Development / Meta](#development-and-meta)
15
+
16
+
17
+
<aname="overview-and-resources"></a>
18
+
## Overview / Resources
4
19
5
20
*[Srcset and sizes by Eric Portis](https://ericportis.com/posts/2014/srcset-sizes/). A seminal article on `srcset`, `sizes`, and `picture`. Explains why they're necessary, and how they work together.
6
21
*[Using imgix with `<picture>`](https://docs.imgix.com/tutorials/using-imgix-picture-element). Discusses the differences between art direction and resolution switching, and provides examples of how to accomplish art direction with imgix.
7
22
*[Responsive Images with `srcset` and imgix](https://docs.imgix.com/tutorials/responsive-images-srcset-imgix). A look into how imgix can work with `srcset` and `sizes` to serve the right image.
8
23
9
24
10
-
## Installation & Usage
25
+
<aname="installation"></a>
26
+
## Installation
11
27
12
28
There are several ways to install imgix.js. The appropriate method depends on your project.
13
29
14
-
1.`npm install --save imgix.js`
15
-
2.`bower install --save imgix.js`
16
-
3.[Download the latest release of imgix.js](https://github.com/imgix/imgix.js/releases/latest), and extract`dist/imgix.js` or `dist/imgix.min.js` to your project.
30
+
1.**npm**: `npm install --save imgix.js`
31
+
2.**Bower**: `bower install --save imgix.js`
32
+
3.**Manual**: [Download the latest release of imgix.js](https://github.com/imgix/imgix.js/releases/latest), and use`dist/imgix.js` or `dist/imgix.min.js`.
17
33
18
-
After you've included imgix.js on your page, you just have to run it (you'll probably want to put this at the bottom of your page, just before the `</body>` tag):
34
+
After you've included imgix.js on your page, you just have to run it (you'll probably want to put this at the bottom of your page, just before the `</body>` tag). This code will scan the page for `img` and `source` tags that need to be processed, and initialize them:
19
35
20
36
```html
21
37
<scriptsrc="imgix.js"></script>
22
38
<script>
39
+
// Specify your imgix host. For these docs, we'll use `assets.imgix.net`.
40
+
imgix.config.host='assets.imgix.net';
41
+
// Find and initialize all uninitialized `img` or `source` tags with
42
+
// `ix-src` or `ix-path` attributes.
23
43
imgix.init();
24
44
</script>
25
45
```
26
46
27
-
Now that everything's set, you can start creating responsive images. There are a few ways to do this. First of all, you can use an `img` tag with the `ix-src` attribute:
47
+
By setting the `imgix.config.host` value to your imgix hostname, you enable the use of `ix-path` and `ix-params` to define images, instead of having to manually type URLs out in `imgix-src`. This has several advantages:
48
+
49
+
1.`ix-params` automatically URL/Base64 encodes your specified params, as appropriate.
50
+
2.`ix-params` is a JSON string, which is easier to read than a URL, and can be generated by other tools if necessary.
51
+
3. Not having to re-type `https://my-source.imgix.net` helps keep your code DRY.
52
+
53
+
54
+
<aname="usage"></a>
55
+
## Usage
56
+
57
+
Now that everything's installed and set up, you can start adding responsive images to the page. There are a few ways to do this.
58
+
59
+
<aname="ix-src"></a>
60
+
### `ix-src`
61
+
62
+
The simplest way to use imgix.js is to create an `img` tag with the `ix-src` attribute:
28
63
29
64
```html
30
65
<img
@@ -53,23 +88,11 @@ This will generate HTML something like the following:
53
88
54
89
Since imgix can generate as many derivitive resolutions as needed, imgix.js calculates them programmatically, using the dimensions you specify (note that the `w` and `h` params scale appropriately to maintain the correct aspect ratio). All of this information has been placed into the `srcset` and `sizes` attributes. Because of this, imgix.js no longer needs to watch or change the `img` tag, as all responsiveness will be handled automatically by the browser.
55
90
56
-
If you set the `imgix.config.host` value to your imgix hostname, you can use `ix-path` and `ix-params` to define images, instead of having to manually type URLs out in `imgix-src`. This has several advantages:
57
91
58
-
1.`ix-params` automatically URL/Base64 encodes your specified params, as appropriate.
59
-
2.`ix-params` is a JSON string, which is easier to read than a URL, and can be generated by other tools if necessary.
60
-
3. Not having to re-type `https://my-source.imgix.net` helps keep your code DRY.
61
-
62
-
Here's an example of how to set that up:
63
-
64
-
```html
65
-
<scriptsrc="imgix.js"></script>
66
-
<script>
67
-
imgix.config.host='assets.imgix.net';
68
-
imgix.init();
69
-
</script>
70
-
```
92
+
<aname="ix-path-and-ix-params"></a>
93
+
### `ix-path` and `ix-params`
71
94
72
-
And here's how the previous example would be written out using `ix-path` and `ix-params` instead of `ix-src`:
95
+
Here's how the previous example would be written out using `ix-path` and `ix-params` instead of `ix-src`. Regardless of which method you choose, the end result in-browser will be the same.
@@ -80,18 +103,28 @@ And here's how the previous example would be written out using `ix-path` and `ix
80
103
}'alt="A hot air balloon on a sunny day">
81
104
```
82
105
83
-
Regardless of which method you choose, the end result in-browser will be the same.
106
+
<aname="picture-tags"></a>
107
+
### `picture` tags
84
108
109
+
If you need art directed images, imgix.js plays nicely with the `picture` tag. This allows you to specify more advanced responsive images, by changing things such as the crop and aspect ratio for different screens.
85
110
86
-
### Browser Compatibility Notes
111
+
TODO
112
+
113
+
114
+
<aname="browser-support"></a>
115
+
### Browser Support
87
116
88
117
* If you are using [Base64 variant params](https://docs.imgix.com/apis/url#base64-variants) and need IE <= 9 support, we recommend using a polyfill for `atob`/`btoa`, such as [Base64.js](https://github.com/davidchambers/Base64.js).
89
118
* By default, browsers that don't support [`srcset`](http://caniuse.com/#feat=srcset), [`sizes`](http://caniuse.com/#feat=srcset), or [`picture`](http://caniuse.com/#feat=picture) will gracefully fall back to the default `img``src` when appropriate. If you want these browsers to display responsive images in these cases instead, we recommend using [Picturefill](https://github.com/scottjehl/picturefill).
90
119
120
+
<aname="development-and-meta"></a>
121
+
## Development / Meta
122
+
123
+
Drift was made by [imgix](http://imgix.com). It's licensed under the BSD 2-Clause license (see the [license file](https://github.com/imgix/imgix.js/blob/master/LICENSE.md) for more info). Any contribution is absolutely welcome, but please review the [contribution guidelines](https://github.com/imgix/imgix.js/blob/master/CONTRIBUTING.md) before getting started.
91
124
92
-
## Development
125
+
Here's a quick intro to getting started with development on imgix.js:
0 commit comments