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

    1.4.0 • Public • Published

    npm version min+gzip min+br

    Statements Branches Functions Lines


    A web component that renders YouTube embeds faster. The ShadowDom web component version of Paul's lite-youtube-embed.


    • No dependencies; it's just a vanilla web component.
    • It's fast yo.
    • It's Shadow Dom encapsulated!
    • It's responsive 16:9
    • It's accessible via keyboard and will set ARIA via the videotitle attribute
    • It's locale ready; you can set the videoplay to have a properly locale based label
    • Set the start attribute to start at a particular place in a video
    • You can set autoload to use Intersection Observer to load the iframe when scrolled into view.
    • Loads placeholder image as WebP with a Jpeg fallback
    • new in v1.1: Adds nocookie attr for use with use youtube-nocookie.com as iframe embed uri
    • new in v1.2: Adds playlistid for playlist loading interface support
    • new in v1.3: Adds loading=lazy to image placeholder for more perf with posterloading attr if you'd like to use eager
    • new in v1.4: Adds short attr for enabling experimental YouTube Shorts mobile interaction support. See (example video)[https://www.youtube.com/watch?v=aw7CRQTuRfo] for details.

    Install via package manager

    This web component is built with ES modules in mind and is available on NPM:

    To install, use your package manager of choice:

    npm i @justinribeiro/lite-youtube
    # or
    yarn add @justinribeiro/lite-youtube

    After install, import into your project:

    import '@justinribeiro/lite-youtube';

    Install with CDN

    If you want the paste-and-go version, you can simply load it via CDN:

    <script type="module" src="https://cdn.jsdelivr.net/npm/@justinribeiro/lite-youtube@1.4.0/lite-youtube.js"></script>

    Basic Usage

    <lite-youtube videoid="guJLfqTFfIw"></lite-youtube>

    Playlist Usage

    Setting the YouTube playlistid allows the playlist interface to load on interaction. Note, this still requires a videoid for to load a placeholder thumbnail as YouTube does not return a thumbnail for playlists in the API.


    Add Video Title

      videotitle="This is a video title"

    Update interface for Locale

      videotitle="Mis hijos se burlan de mi español"

    Style It

    Height and Width are responsive in the component.

      .styleIt {
        width: 400px;
        margin: auto;
    <div class="styleIt">
      <lite-youtube videoid="guJLfqTFfIw"></lite-youtube>

    Enable YouTube Shorts interaction on mobile

    See the example video of how this feature works for additional details.

    <lite-youtube videoid="vMImN9gghao" short></lite-youtube>

    AutoLoad with IntersectionObserver

    Uses Intersection Observer if available to automatically load the YouTube iframe when scrolled into view.

    <lite-youtube videoid="guJLfqTFfIw" autoload> </lite-youtube>

    Set a video start time

    <!-- Start at 5 seconds -->
    <lite-youtube videoid="guJLfqTFfIw" videoStartAt="5"></lite-youtube>

    Fine tune the poster quality for a video


    YouTube QueryParams

    Use any YouTube Embedded Players and Player Parameters you like.

    Note: the exception to this rule is the autoplay param; because of the nature of the performance loading and the inconsistency of usage, that parameter generally does not work. See this comment for details.

    <lite-youtube videoid="guJLfqTFfIw" params="controls=0&enablejsapi=1">


    The web component allows certain attributes to be give a little additional flexibility.

    Name Description Default
    videoid The YouTube videoid ``
    playlistid The YouTube playlistid; requires a videoid for thumbnail ``
    videotitle The title of the video Video
    videoplay The title of the play button (for translation) Play
    videoStartAt Set the point at which the video should start, in seconds 0
    posterquality Set thumbnail poster quality (maxresdefault, sddefault, mqdefault, hqdefault) hqdefault
    posterloading Set img lazy load attr loading for poster image lazy
    nocookie Use youtube-nocookie.com as iframe embed uri false
    autoload Use Intersection Observer to load iframe when scrolled into view false
    short Show 9:16 YouTube Shorts-style interaction on mobile devices false
    params Set YouTube query parameters ``


    The web component fires events to give the ability understand important lifecycle.

    Event Name Description Returns
    liteYoutubeIframeLoaded When the iframe is loaded, allowing us of JS API detail: { videoId: this.videoId }


    npm i @justinribeiro/lite-youtube

    DownloadsWeekly Downloads






    Unpacked Size

    40.9 kB

    Total Files


    Last publish


    • justinribeiro