Notwithstanding Precautions, Misadventure

    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


    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)


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


    To show a placeholder until the iframe embed has loaded:

    <facade-script iframe src="">

    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.
      <button>Play video</button>

    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.


    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 🤓)

      props="{\"title\":\"Title of iframe\"}"

    Or in JSX:

      props={{ title: 'Title of iframe' }}

    See this readme for a full list of config options.


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


    npm i facade-script

    DownloadsWeekly Downloads






    Unpacked Size

    749 kB

    Total Files


    Last publish


    • georgeadamson