|
3 | 3 |
|
4 | 4 | [](https://travis-ci.org/malchata/yall.js) |
5 | 5 |
|
6 | | -yall.js is a very small image lazy loader for reasonably modern browsers (back to IE11) that weighs in at 1.1 KB uglified (650 bytes with gzip/545 bytes with Brotli). It depends on `classList`, `querySelectorAll`, and supports the `<picture>` element and `srcset`. yall.js will also use `IntersectionObserver` if available, but will fall back to more traditional means if it's not. If you want to try out yall.js, grab a copy from the releases tab. Or you can clone the repo and check out the `test` folder. If you want to tinker, work with the copy in the `src` folder and build using `npm run build` (requires `npx`). |
| 6 | +yall.js is a very small image and video lazy loader for reasonably modern browsers (back to IE11) that weighs in at 1.18 KB uglified (688 bytes with gzip/568 bytes with Brotli). It uses on `classList`, `querySelector`. It supports lazy loading `<img>` and `<picture>` with `src`/`srcset`, as well as `<video>`. yall.js will also use `IntersectionObserver` if available, but will fall back to throttled `scroll`/`resize` event handlers if it's not. If you want to try out yall.js, grab a copy from the releases tab. Or you can clone the repo and check out the `test` folder. If you want to tinker, work with the copy in the `src` folder and build using `npm run build` (requires `npx`). |
7 | 7 |
|
8 | 8 | ## Usage Pattern |
9 | 9 |
|
10 | 10 | yall.js assumes a lot, but because it does, it's very straightforward. Here's the simplest `<img>` element use case: Just add a class of `lazy` to an `<img>` element you want to lazy load, and point the `data-src` attribute to the desired image source: |
11 | 11 |
|
12 | 12 | ```html |
| 13 | +<!-- Simple <img> example --> |
13 | 14 | <img class="lazy" data-src="/img/image-to-lazy-load.jpg" src="/img/placeholder.jpg" alt="Alternative text to describe image."> |
14 | 15 | ``` |
15 | 16 |
|
16 | | -An optional (but recommended) placeholder can be specified in the `src` attribute. This will be replaced by the lazy loader when the element is scrolled into view. |
| 17 | +An optional (but recommended) placeholder can be specified in the `src` attribute, which will be replaced by yall.js when the image is lazily loaded. If you go this route, be sure to specify `width` and `height` attributes to minimize layout shifting. |
17 | 18 |
|
18 | 19 | You can also use yall.js on `srcset` attributes, too: |
19 | 20 |
|
20 | 21 | ```html |
| 22 | +<!-- A somewhat more complex <img> + srcset example --> |
21 | 23 | <img class="lazy" data-srcset="/img/image-to-lazy-load-2x.jpg 2x, /img/image-to-lazy-load-1x.jpg 1x" data-src="/img/image-to-lazy-load-1x.jpg" src="/img/placeholder.jpg" alt="Alternative text to describe image."> |
22 | 24 | ``` |
23 | 25 |
|
24 | 26 | You can use it on `<picture>` elements, too! |
25 | 27 |
|
26 | 28 | ```html |
| 29 | +<!-- A more complex <picture> + <img> + srcset example --> |
27 | 30 | <picture> |
28 | 31 | <source data-srcset="/img/image-to-lazy-load.webp" type="image/webp"> |
29 | 32 | <source data-srcset="/img/image-to-lazy-load.jpg" type="image/jpeg"> |
30 | 33 | <img data-src="/img/image-to-lazy-load.jpg" src="/img/placeholder.jpg" class="lazy" alt="Alternative text to describe image."> |
31 | 34 | </picture> |
32 | 35 | ``` |
33 | 36 |
|
| 37 | +And now as of the 1.2.0 release, you can use it on `<video>` elements! This is useful if you are replacing animated GIFs with autoplaying videos (which are usually much smaller). |
| 38 | + |
| 39 | +```html |
| 40 | +<!-- Lazy load that video! --> |
| 41 | +<video class="lazy" autoplay loop muted> |
| 42 | + <source data-src="video.webm" type="video/webm"> |
| 43 | + <source data-src="video.ogv" type="video/ogg"> |
| 44 | + <source data-src="video.mp4" type="video/mp4"> |
| 45 | +</video> |
| 46 | +``` |
| 47 | + |
| 48 | +The pattern is largely the same as it is with the `<picture>` use case, only the `lazy` class is applied to the `<video>` element. **Pro tip:** If you're embedding videos that don't emulate animated GIF behavior (i.e., non autoplaying video), it's probably best to lean on the `preload` attribute to defer loading rather than using yall.js. Read more about `preload` [in the MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video). |
| 49 | + |
34 | 50 | ## What about users without JavaScript? |
35 | 51 |
|
36 | 52 | Easy! Slap on some `<noscript>` goodness: |
37 | 53 |
|
38 | 54 | ```html |
| 55 | +<!-- For users without JavaScript --> |
39 | 56 | <img class="lazy" data-src="/img/image-to-lazy-load.jpg" src="/img/placeholder.jpg" alt="Alternative text to describe image."> |
40 | 57 | <noscript> |
41 | 58 | <img src="/img/image-to-lazy-load.jpg" alt="Alternative text to describe image."> |
42 | 59 | </noscript> |
| 60 | + |
| 61 | +<!-- Here's a <video> example, too --> |
| 62 | +<video class="lazy" autoplay loop muted> |
| 63 | + <source data-src="video.webm" type="video/webm"> |
| 64 | + <source data-src="video.ogv" type="video/ogg"> |
| 65 | + <source data-src="video.mp4" type="video/mp4"> |
| 66 | +</video> |
| 67 | +<noscript> |
| 68 | + <video autoplay loop muted> |
| 69 | + <source src="video.webm" type="video/webm"> |
| 70 | + <source src="video.ogv" type="video/ogg"> |
| 71 | + <source src="video.mp4" type="video/mp4"> |
| 72 | + </video> |
| 73 | +</noscript> |
43 | 74 | ``` |
44 | 75 |
|
45 | 76 | Then place a `no-js` class on the `<html>` element, and finally add this JavaScript one-liner in the `<head>` of the document: |
46 | 77 |
|
47 | 78 | ```html |
| 79 | +<!-- Remove the no-js class on the <html> element if JavaScript is on --> |
48 | 80 | <script>document.documentElement.classList.remove("no-js");</script> |
49 | 81 | ``` |
50 | 82 |
|
51 | 83 | This snippet will remove the `no-js` class from the `<html>` element as the page loads, but if JavaScript is turned off, this will never happen. From there, you can add some CSS that hides elements with a class of `lazy` when the `no-js` class is present on the `<html>` element: |
52 | 84 |
|
53 | 85 | ```css |
| 86 | +/* Hide .lazy elements if JavaScript is off */ |
54 | 87 | .no-js .lazy{ |
55 | 88 | display: none; |
56 | 89 | } |
57 | 90 | ``` |
58 | 91 |
|
59 | | -To see everything in action, check out the demos in the `test` folder. |
| 92 | +To see all use cases in action, check out the demos in the `test` folder and go from there. |
60 | 93 |
|
61 | 94 | ## Limitations |
62 | 95 |
|
63 | | -yall.js will only attach listeners to markup that has been sent by the server. Lazy-loaded markup injected into the DOM using this pattern will not be recognized. This makes yall.js just fine for the vast majority of use cases, but if you have some really complex stuff going on, you should find a more feature-rich lazy loader. |
| 96 | +yall.js will only attach listeners to markup sent by the server. Lazy-loaded markup injected into the DOM using this pattern will not be recognized. This makes yall.js just fine for the vast majority of use cases, but if you have really complex stuff going on (such as SPA environments), you should find a more feature-rich lazy loader. Eventually, I will modify yall.js to expose methods to destroy/init. |
64 | 97 |
|
65 | | -yall.js also doesn't try to guess at placeholder sizes to minimize layout shifting. I would *highly recommend* you specify a placeholder `src` in your `<img>` tags, or develop a CSS placeholder solution. For example, you could serve an extremely low quality version of an image that has a heavy gaussian blur effect. This technique signals to the user that an image will appear in that space, but doesn't push many extra bytes down the wire. |
| 98 | +yall.js also doesn't try to guess at placeholder sizes to minimize layout shifting. I would _highly recommend_ you specify a placeholder `src` in your `<img>` tags, or develop a CSS placeholder solution. For example, you could serve an extremely low quality version of an image that has a heavy gaussian blur effect. This technique signals to the user that an image will appear in that space, but doesn't push many extra bytes down the wire. |
66 | 99 |
|
67 | 100 | ## Contributing |
68 | 101 |
|
69 | | -I'm not interested in expanding the functionality by much unless a good case can be made for increasing its performance without making it huge. The goal of yall.js is to be as small as reasonably possible while maintaining functionality. |
| 102 | +If you have an idea, file an issue and let's talk about it. Unsolicited pull requests for new features will generally be rejected, unless those requests contain bug fixes. Generally speaking, I want to avoid adding new features in lieu of keeping this library very, very small. |
70 | 103 |
|
71 | 104 | ## Special thanks |
72 | 105 |
|
73 | | -Props to [Kamran Ayub](https://github.com/kamranayub) for his tremendous help with performance tuning this script, and to [Anthony Gore](https://twitter.com/anthonygore) for fixing an elusive bug in my intersection observer code where sometimes the last image on a page would not lazy load. |
| 106 | +Props to [Kamran Ayub](https://github.com/kamranayub) for his tremendous help with performance tuning this script, and to [Anthony Gore](https://twitter.com/anthonygore) for fixing an elusive bug in my `IntersectionObserver` code where sometimes the last image on a page would not lazy load. |
74 | 107 |
|
75 | 108 | ## Why another dumb lazy loader? |
76 | 109 |
|
77 | | -I explain how to write a lazy loader in Chapter 6 of my book [Web Performance in Action](https://www.manning.com/books/web-performance-in-action?a_aid=webopt&a_bid=63c31090) from Manning Publications. Otherwise, I wouldn't have bothered. The lazy loader in the book is much different (and more improved!) than what you'll find here. |
| 110 | +I explain how to write a lazy loader in Chapter 6 of my book [Web Performance in Action](https://www.manning.com/books/web-performance-in-action?a_aid=webopt&a_bid=63c31090) from Manning Publications. Otherwise, I wouldn't have bothered. The lazy loader in the book is much different (and less powerful) than what you'll find here. |
0 commit comments