media-loader

Take control over your media loading 💪

MediaLoader is a versatile React component that provides fine-grained control over the loading of media assets such as images, videos, and audio files. It offers a customizable loading strategy, allowing developers to prioritize resources and optimize user experience.

With MediaLoader, you can effortlessly manage the loading process, dynamically loading media content based on user interactions, viewport visibility and much more. Whether you're building a gallery, a multimedia-rich website, or an application with heavy media content, MediaLoader empowers you to deliver a seamless and performant user experience.

MediaLoader is designed to be as non-intrusive as possible, seamlessly integrating into your existing React applications without imposing a heavy footprint. It provides a lightweight wrapper around your current media, without requiring a complete overhaul of your codebase.

Installation

You can install MediaLoader via npm or yarn. Make sure you have Node.js and npm (or yarn) installed on your machine before proceeding.

yarn

yarn add @pedalboard/media-loader

npm

npm install @pedalboard/media-loader

Usage example

In order to have the MediaLoader take control you need to wrap the media you want to control with it. So say you have this JSX:

<img src="/assets/image-04.jpg" alt="image-04"></img>
<img src="/assets/image-05.jpg" alt="image-05"></img>
<img src="/assets/image-06.jpg" alt="image-06"></img>
<div>
    <img src="/assets/image-09.jpg" alt="image-09"></img>
</div>

You will wrap it with the MediaLoader and provide a loading strategy:

import MediaLoader from '@pedalboard/media-loader';
...

<MediaLoader
    loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
        // You loading strategy here
    }}
>
    <img src="/assets/image-04.jpg" alt="image-04"></img>
    <img src="/assets/image-05.jpg" alt="image-05"></img>
    <img src="/assets/image-06.jpg" alt="image-06"></img>
    <div>
        <img src="/assets/image-09.jpg" alt="image-09"></img>
    </div>
</MediaLoader>

In the following code example we have 3 images, when the image container is clicked on it starts sliding to the right. Our loading strategy here is: "When the left css value of the image is above 300, load the image. (Watch the result in the link below)

import MediaLoader from '@pedalboard/media-loader';
...

<MediaLoader
    loadingStrategy={(mediaHTMLElementRefs, loadMedia) => {
        const monitor = (target) => {
            const computedStyle = getComputedStyle(target.parentElement);
            const currentLeft = parseFloat(computedStyle.left);
            // If the image container reach a certain left then load it
            if (currentLeft > 300) {
                loadMedia(target);
                return;
            }

            // Continue monitoring in the next frame
            requestAnimationFrame(() => monitor(target));
        };

        mediaHTMLElementRefs.forEach((mediaHTMLElementRef) => {
            let target = mediaHTMLElementRef.current;
            if (target) {
                requestAnimationFrame(() => monitor(target));
            }
        });
    }}
>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-01.jpg" alt="image-09" className="run"></img>
        <div>And now me</div>
    </div>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-02.jpg" alt="image-09" className="run"></img>
        <div>Quick! Click me ;)</div>
    </div>
    <div
        className="image-container"
        onClick={(event) => {
            (event.target as HTMLDivElement).classList.add('animate-media');
        }}
    >
        <img src="/assets/image-03.jpg" alt="image-09" className="run"></img>
        <div>Click me ;)</div>
    </div>
</MediaLoader>

The loadingStrategy prop

The loadingStrategy prop is a function which defines how we would like to trigger the load for our wrapped media.
It receives 2 arguments - An array of the media element refs and the loadMedia function. When you call the loadMedia function with a given ref it will load the associated media for it, whether it is an image, video or audio.

📽️ Watch the result

Check out the FAQ below for more details

Storybook

You can also see more example with their code in the project's online Storybook.
If you wish to run Storybook locally, clone the project, install the dependencies and run yarn storybook

FAQ

Contribution

see the CONTRIBUTING.md file for details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.