Notorious Preying Mantis

    facade-script
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    npm version Minzipped size Tree shaking Dependency count Built With Stencil

    <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.

    Install

    npm i facade-script

    DownloadsWeekly Downloads

    339

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    749 kB

    Total Files

    61

    Last publish

    Collaborators

    • georgeadamson