Nine Pomeranian Monsters

    viewport-action

    1.0.1 • Public • Published

    Viewport Action

    Provides a way with extra configuration options to execute a handler when a given element is on view.

    Few things to know:

    • It checks when an element is on view as soon as it's added to viewportAction.
    • It skips all elements that are not on view at the moment the event triggers the handler. This means it will not call the handlers for elements that where just scrolled over.

    Example

    https://codepen.io/rooyva/pen/aPWNXQ

    Installation

    Using NPM

    npm i viewport-action

    Using CDN

    <script src="https://cdn.jsdelivr.net/npm/viewport-action@1.0.0/dist/viewportAction.min.js"></script>

    Download files

    You can download the distribution files from https://github.com/darlesson/viewport-action/tree/master/dist

    Usage

    // Importing with ES6
    import viewportAction from 'viewport-action';
    // Using RequireJS
    require(['./src/viewportAction.min'], (viewportAction) => {
    
    });
    // Global reference when not using Require JS
    window.viewportAction;

    Bind a handler to an element

    You can add elements or selectors with the handlers. The add method waits for whenDocumentReady to execute a callback when the document is ready. Only one element can be bound per handler.

    viewportAction.add('#selector', (e) => { /* Code here */ });
    
    // or
    
    viewportAction.add(document.getElementById('selector'), (e) => { /* Code here */ });

    The event object

    The event object is an instance of the custom ViewportEvent class. It returns details that can be used to determine the conditions to change the element bound to the handler.

    {
        // The event name.
        type: 'viewport',
        // Resize or scroll event instances.
        originalEvent: event,
        // The element bound with the handler.
        target: element,
        // The same as target.
        currentTarget: element,
        // The same as target.
        srcElement: element,
        // The timeStamp from `originalEvent.timeStamp`.
        timeStamp: 345,
        // The event detail object.
        detail: {
            // The element's area visible on the viewport
            availableArea: 318425.015625,
            // The space between the bottom of the viewport and the bottom
            // of the element while in the viewport.
            availableTop: 0,
            // The space between the top of the viewport and the top of the
            // element while in the viewport.
            availableBottom: 440.421875,
            // The element's height shown in the viewport.
            availableHeight: 440.421875,
            // The space between the left of the viewport and the left of the
            // element while in the viewport.
            availableLeft: 118,
            // The space between the right of the viewport and the right of the
            // element while in the viewport.
            availableRight: 841,
            // The element's width shown in the viewport.
            availableWidth: 723,
            // The same as `element.getBoundingClientRect().top`.
            top: -63.578125,
            // The same as `element.getBoundingClientRect().bottom`.
            bottom: 440.421875,
            // The same as `element.getBoundingClientRect().height`.
            height: 504,
            // The same as `element.getBoundingClientRect().left`.
            left: 118,
            // The same as `element.getBoundingClientRect().right`.
            right: 841,
            // The same as `element.getBoundingClientRect().width`.
            width: 723
        }
    }

    Setting options

    Below are some options that can be passed when adding the element and handler and their default values.

    const options = {
        // How long the handler will wait after the original event stops triggering.
        wait: 50,
        // Whether to unbind the handler after executed for the first time.
        once: false
    };
    
    viewportAction.add('#selector', (e) => { /* Code here */ }, options);

    Executing the handler once

    You can have the handler unbinding on the first time the element is on the viewport.

    const options = {
        once: true
    };
    
    viewportAction.add('#selector', (e) => {
        e.target.innerText = 'Element on viewport.';
    }, options);

    Unbing the handler when meeting a condition

    You can allow the handler to be executed until a condition is met and only then unbind it.

    viewportAction.add('#selector', (e) => {
    
        // Load an image inside the element when the area visible is bigger
        // than 1000 pixels.
        if (e.detail.availableArea > 1000) {
    
            e.target.innerText = 'Element on viewport.';
    
            // Remove handler
            e.removeHandler();
        }
    });

    Check whether an element is on the viewport

    You can check whether an element is on the viewport on demand without waiting for document changes.

    // You can use a selector or the element itself
    viewportAction.check('#selector', (e) => {
        // Code here
    }, () => {
        // Optional callback handler if the element is not on the document. Just one of the
        // 2 callbacks is called.
    });

    Testing and developing

    You can run the command below to build the application and run a server to test and deveop.

    npm start
    

    Open http://localhost:9000/ on your browser.

    License

    MIT License

    Install

    npm i viewport-action

    DownloadsWeekly Downloads

    3

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    24.4 kB

    Total Files

    5

    Last publish

    Collaborators

    • darlesson