facade-script

v1.0.0

Published

2 years ago

Lazyloader for any script or embed

Downloads

443

0High
0Medium
0Low

georgeadamson

lazyload lazy load late load interaction pattern embed

<facade-script>

A little Custom Element to lazy-load or late-load any script or embed, only when the user needs it.

For example to only load a YouTube iFrame when the user scrolls down to it.

TLDR usage:

JS: <facade-script src="/lazyload/any/script.js"></facade-script> or
iFrame: <facade-script iframe src="/lazyload/any/embed.js"></facade-script> or
iFrame video: <facade-script iframe trigger="click" src="/any/youtube.js">Play</facade-script>

Perfect for the Mindful-loading pattern or Import on interaction pattern.

Loading can be triggered when you:

Scroll it into view (lazyload is the default)
Click it (for example your own Play button)

Step 1 of 2

Include the script in your page: (~8.2kb gzipped)

<script
  defer
  type="module"
  src="https://unpkg.com/facade-script/dist/facade-script/facade-script.esm.js"
></script>
<script
  defer
  nomodule
  src="https://unpkg.com/facade-script/dist/facade-script/facade-script.js"
></script>

☝️ Recommend using defer for minimal impact on page load speed and because there's typically no hurry to fetch this script, but that's up to you.

Step 2 of 2

Then you simply use the facade-script tag instead of a standard script or iframe...

To lazyload a script:

A <script> tag will only be added to the page when the user scrolls this into view.

<facade-script src="https://path/to/a/script.js"></facade-script>

To lazyload a YouTube video:

An <iframe> tag will only be added to the page when the user scrolls this into view.

Recommended: For improved accessibility, supply a title attribute for the iframe too. See props below.

<facade-script
  iframe
  src="https://www.youtube.com/embed/GTUruS-lnEo"
></facade-script>

To show a placeholder until the iframe embed has loaded:

<facade-script iframe src="https://www.youtube.com/embed/GTUruS-lnEo">
  <p>Loading...</p>
</facade-script>

Advanced use cases

`once` (boolean)

Use this to ensure a script is only loaded once on the page, even when there are multiple instances of the tag. Without this flag, every instance of this component will add the script to the page when triggered.

<facade-script once src="https://path/to/a/script.js"></facade-script>

`global` (boolean)

By default the script will be added to the page within the facade-script tags. Use the global option to add the script to the <head> instead.

<facade-script global once src="https://path/to/a/script.js"></facade-script>

`trigger` ("now" | "lazy" | "click")

When should the script be added to the page?

now - Immediately. Much like a standard script. Kinda pointless but useful when debugging.
lazy - When this element is scrolled into view. (Default)
click - When this element is clicked.

<facade-script
  iframe
  trigger="click"
  src="https://www.youtube.com/embed/GTUruS-lnEo"
>
  <button>Play video</button>
</facade-script>

`wait="..."` (milliseconds)

After being triggered, delay n milliseconds before adding the script or iframe to the page. You could combine it with trigger="now" to make the script run n milliseconds after DOM load.

<facade-script
  iframe
  wait="2000"
  src="https://www.youtube.com/embed/GTUruS-lnEo"
></facade-script>

`props` (to add attributes to your script or iframe)

Sometimes you need to set attributes on the <script> or <iframe> when it gets created.

Attributes can be supplied as a map of {key:value} supplied as JSON (or as an object if you're using JSX).

For example, iframes should have a title attribute: (Yes yes I know it's not very beautiful but that's the nature of JSON in HTML, so if you have a better solution that does not bloat the code unnecessarily then be sure to let me know 🤓)

<facade-script
  iframe
  src="https://www.youtube.com/embed/GTUruS-lnEo"
  props="{\"title\":\"Title of iframe\"}"
></facade-script>

Or in JSX:

<facade-script
  iframe
  src="https://www.youtube.com/embed/GTUruS-lnEo"
  props={{ title: 'Title of iframe' }}
></facade-script>

See this readme for a full list of config options.

Notes

Curently in Beta. Appears stable but still testing in the wild.
~8.2kb when you use the CDN link (minified & gzipped). I have yet to see if I can make it smaller with some more analysis.
To do: Solutions for better accessibility of placeholders etc.
To do: Consider what happens during prerender. This should probably not render the script or iframe when running server-side.
But why is it called facade-script? Because of the Facade Pattern: As well as lazyloading it can render a fake UI or placeholder until the real third party loads.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme