Skip to content

Commit 19e7380

Browse files
committed
docs: add further information to the README
1 parent 4b08765 commit 19e7380

1 file changed

Lines changed: 28 additions & 4 deletions

File tree

README.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ You may optionally load via NPM or Bower:
3939
$ npm install loading-attribute-polyfill-with-serviceworker
4040
$ bower install loading-attribute-polyfill-with-serviceworker
4141

42+
## Integration
43+
4244
Include one of the provided JavaScript files depending on your setup plus the CSS file:
4345

4446
```html
@@ -52,15 +54,37 @@ or e.g. within JS
5254
import loadingAttributePolyfill from "node_modules/loading-attribute-polyfill-with-serviceworker/dist/loading-attribute-polyfill-with-serviceworker.module.js";
5355
```
5456

57+
### Additional information on your image and document (iframe) references
58+
5559
Afterwards, you need to add a query to all of your `<img>` (`?loading=lazy&image-width=250&image-height=150`) and `<iframe>` (`?loading=lazy`) HTML tags (in the case of `<picture>` use the complementary `<source>` HTML tags) that you'd like to lazy load. The included `image-width` and `image-height` values should match the `width`- and `height`-attribute values of each asset.
5660

61+
#### Generally set dimensions on your images
62+
5763
Please keep in mind that it's important to even also include `width` and `height` attributes on `<img>` HTML tags, as the browser could determine the aspect ratio via those two attributes values being set (even if you overwrite them via CSS), compare to the great work by Jen Simmons on this topic, e.g. within these articles <https://css-tricks.com/do-this-to-improve-image-loading-on-your-website/> (with video) or <https://css-tricks.com/what-if-we-got-aspect-ratio-sized-images-by-doing-almost-nothing/>
5864

5965
And please "Avoid lazy-loading images that are in the first visible viewport", compare to [the article "Browser-level image lazy-loading for the web"](https://web.dev/browser-level-image-lazy-loading/#avoid-lazy-loading-images-that-are-in-the-first-visible-viewport) published on web.dev:
6066

6167
> You should avoid setting `loading=lazy` for any images that are in the first visible viewport. It is recommended to only add `loading=lazy` to images which are positioned below the fold, if possible.
6268
63-
### Simple image
69+
### Register a Service Worker
70+
71+
Furthermore you would either need to integrate the code out of [loading-attribute-polyfill.sw.js](loading-attribute-polyfill.sw.js) to your existing [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker) or register one by yourself – please keep in mind that it's very important to add the feature detection to the Service Workers URL within the `navigator.serviceWorker.register` methods parameter, as we're transfering that information on the users enviroments capabilities via this way.
72+
73+
```javascript
74+
if ("serviceWorker" in navigator) {
75+
// Differentiate in between the Service Worker scripts for the different browser capabilities / support
76+
navigator.serviceWorker.register(
77+
"loading-attribute-polyfill.sw.js?loading-images=" +
78+
("loading" in HTMLImageElement.prototype) +
79+
"&loading-iframes=" +
80+
("loading" in HTMLIFrameElement.prototype)
81+
);
82+
}
83+
```
84+
85+
### Example code
86+
87+
#### Simple image
6488

6589
```html
6690
<img
@@ -72,7 +96,7 @@ And please "Avoid lazy-loading images that are in the first visible viewport", c
7296
/>
7397
```
7498

75-
### Image wrapped in a picture tag
99+
#### Image wrapped in a picture tag
76100

77101
```html
78102
<picture>
@@ -99,7 +123,7 @@ And please "Avoid lazy-loading images that are in the first visible viewport", c
99123
</picture>
100124
```
101125

102-
### Image with `srcset`
126+
#### Image with `srcset`
103127

104128
```html
105129
<img
@@ -115,7 +139,7 @@ And please "Avoid lazy-loading images that are in the first visible viewport", c
115139
/>
116140
```
117141

118-
### Iframe
142+
#### Iframe
119143

120144
```html
121145
<iframe

0 commit comments

Comments
 (0)