Skip to content

Commit 20b856b

Browse files
mfranzkemfranzke
committed
docs: added further relevant information on the polyfills usage
1 parent b2fd663 commit 20b856b

File tree

1 file changed

+111
-0
lines changed

1 file changed

+111
-0
lines changed

‎README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,12 +58,123 @@ or e.g. within JS
5858
import loadingAttributePolyfill from "node_modules/loading-attribute-polyfill-with-serviceworker/dist/loading-attribute-polyfill-with-serviceworker.module.js";
5959
```
6060

61+
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.
62+
6163
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/>
6264

6365
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:
6466

6567
> 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.
6668
69+
### Simple image
70+
71+
```html
72+
<img
73+
src="simpleimage.jpg?loading=lazy&image-width=250&image-height=150"
74+
loading="lazy"
75+
alt=""
76+
width="250"
77+
height="150"
78+
/>
79+
```
80+
81+
### Image wrapped in a picture tag
82+
83+
```html
84+
<picture>
85+
<source
86+
media="(min-width: 40em)"
87+
srcset="
88+
simpleimage.huge.jpg?loading=lazy&image-width=250&image-height=150 1x,
89+
simpleimage.huge.2x.jpg?loading=lazy&image-width=250&image-height=150 2x
90+
"
91+
/>
92+
<source
93+
srcset="
94+
simpleimage.jpg?loading=lazy&image-width=250&image-height=150 1x,
95+
simpleimage.2x.jpg?loading=lazy&image-width=250&image-height=150 2x
96+
"
97+
/>
98+
<img
99+
src="simpleimage.jpg?loading=lazy&image-width=250&image-height=150"
100+
loading="lazy"
101+
alt=".."
102+
width="250"
103+
height="150"
104+
/>
105+
</picture>
106+
```
107+
108+
### Image with `srcset`
109+
110+
```html
111+
<img
112+
src="simpleimage.jpg?loading=lazy&image-width=250&image-height=150"
113+
srcset="
114+
simpleimage.1024.jpg?loading=lazy&image-width=250&image-height=150 1024w,
115+
simpleimage.640.jpg?loading=lazy&image-width=250&image-height=150 640w,
116+
simpleimage.320.jpg?loading=lazy&image-width=250&image-height=150 320w
117+
"
118+
sizes="(min-width: 36em) 33.3vw, 100vw"
119+
alt="A rad wolf"
120+
loading="lazy"
121+
/>
122+
```
123+
124+
### Iframe
125+
126+
```html
127+
<iframe
128+
src="iframe.html?loading=lazy"
129+
width="320"
130+
height="180"
131+
loading="lazy"
132+
></iframe>
133+
```
134+
135+
## API
136+
137+
In case that you're dynamically adding HTML elements within the browser, you could call the following method with an included [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) object, like e.g.:
138+
139+
```JavaScript
140+
loadingAttributePolyfill.prepareElement(
141+
document.querySelector('main noscript.loading-lazy')
142+
);
143+
```
144+
145+
In general we recommend to use the Web Standard of customized builtin elements extends to achieve this, by adding an `is`-attribute to the related element and registering those with JavaScript afterwards:
146+
147+
```html
148+
<img
149+
src="simpleimage.jpg?loading=lazy&image-width=250&image-height=150"
150+
loading="lazy"
151+
alt=""
152+
width="250"
153+
height="150"
154+
is="loading-image"
155+
/>
156+
```
157+
158+
```javascript
159+
import loadingAttributePolyfill from "loading-attribute-polyfill-with-serviceworker";
160+
161+
// See https://html.spec.whatwg.org/multipage/indices.html#element-interfaces
162+
// for the list of other DOM interfaces.
163+
class LoadingImages extends HTMLImageElement {
164+
constructor() {
165+
super(); // Always call super() first in the constructor.
166+
// Call for preparing the sample image element included the latest dynamically inserted
167+
loadingAttributePolyfill.prepareElement(this);
168+
}
169+
}
170+
171+
customElements.define("loading-image", LoadingImages, { extends: "img" });
172+
```
173+
174+
compare to the code within [demo/loading-attribute-polyfill.custom-builtin-extend.image.js](demo/loading-attribute-polyfill.custom-builtin-extend.image.js) (or [demo/loading-attribute-polyfill.custom-builtin-extend.iframe.js](demo/loading-attribute-polyfill.custom-builtin-extend.iframe.js) for iframe elements).
175+
176+
In case that you even also would like to support Safari / WebKit browsers, you'll need a polyfill as this engine doesn't support that part of the Custom Elements standard so far: <https://www.npmjs.com/package/@ungap/custom-elements>
177+
67178
## Demo
68179

69180
See the polyfill in action either by downloading / forking this repo and have a look at `demo/index.html`, or at the hosted demo: <https://mfranzke.github.io/loading-attribute-polyfill-with-serviceworker/demo/>

0 commit comments

Comments
 (0)