Have ideas to improve npm?Join in the discussion! »

    react-hover-slideshow

    2.1.12 • Public • Published

    react-hover-slideshow

    Build Status Downloads

    Iterates through an image slideshow based on cursor/touch position.

    Hover slideshow preview

    Requirements

    • Node 10 and higher
    • React 16.8 and higher

    Live demo

    See the Storybook examples

    Installation

    react-hover-slideshow is distributed via npm which comes with Node. To install it as a dependency of your project, simply navigate to your project directory and run:

    • npm i --save react-hover-slideshow

    Peer dependencies

    This module also depends on your project already having react and prop-types as peer dependencies. If you don't yet have those, you can add them as dependencies of your project with this:

    • npm i --save react prop-types

    • ⚠️Warning!⚠️ - this code uses Hooks under the hood, which was introduced in React 16.8. This code will not work with older versions of React.

    Usage

    The simplest way to use react-hover-slideshow is to use the HoverSlideshow component:

    import React from "react";
    import { HoverSlideshow } from "react-hover-slideshow";
     
    // As a function component
    function MyFunctionComponent(props) {
        const imageURLs = [
            "https://example.com/1.jpg",
            "https://example.com/2.jpg",
            "https://example.com/3.jpg"
        ];
     
        return (
            <div>
                <h3>My photo album</h3>
                <HoverSlideshow
                    aria-label="My pretty picture slideshow"
                    images={imageURLs}
                    width="400px"
                    height="300px"
                />
            </div>
        );
    }
     
    // Or as a class component
    class MyClassComponent extends React.Component {
        render() {
            const imageURLs = [
                "https://example.com/1.jpg",
                "https://example.com/2.jpg",
                "https://example.com/3.jpg"
            ];
     
            return (
                <div>
                    <h3>My photo album</h3>
                    <HoverSlideshow
                        aria-label="My pretty picture slideshow"
                        images={imageURLs}
                        width="400px"
                        height="300px"
                    />
                </div>
            );
        }
    }

    Alternatively you can use HoverSlideshowAnimated with the same interface, which will give you a nice crossfade effect. Note that this animated variation depends on the peer dependency react-transition-group, which you can add you your project with the following:

    • npm i --save react-transition-group

    Advanced usage with hooks

    Behind the scenes, the helper components above use the hook useHoverSlideshow. If you wish for more control over the image component markup and CSS, I recommend making a copy of /src/HoverSlideshow.js and making this small change:

    import React from "react";
    import PropTypes from "prop-types";
    -import useHoverSlideshow from "./useHoverSlideshow";
    +import { useHoverSlideshow } from "react-hover-slideshow";

    Then simply use that code as a baseline, and tweak what you like! Here's a quick guide of what's happening in the hook:

    • currentImage - determined by figuring out the user's "cursor progress" over an element, then finding the closest match in the images array passed in. For instance, if images contains two image hrefs, the first image will display until the user's cursor passes over 50% of the element (where 50% is defined horizontally by default).

    • updateHoverSlideshow - updates currentImage based on mousemove and touchmove events

    • resetHoverSlideshow - should be called when the user is no longer interacting with the element (mouseout or touchend). Resets by displaying the first image in the array.

    Local development

    1. Clone this repo: git clone git@github.com:davidcalhoun/react-hover-slideshow.git
    2. Navigate to directory: cd react-hover-slideshow
    3. Install dev dependencies: npm i
    4. Check the scripts section in package.json for a list of available dev commands.

    Install

    npm i react-hover-slideshow

    DownloadsWeekly Downloads

    28

    Version

    2.1.12

    License

    MIT

    Unpacked Size

    1.48 MB

    Total Files

    38

    Last publish

    Collaborators

    • avatar