npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-virtual-container

v0.3.1

Published

Optimise your React apps by only rendering your components when they are in proximity to the viewport.

Downloads

15

Readme

react-virtual-container

Optimise your React apps by only rendering your components when they are in proximity to the viewport.

npm MIT License Travis Codecov

Table of Contents

Introduction

This library provides you with the ability to create a "virtual container", where it's children will only get rendered if the "virtual container" is within a given proximity of the viewport. This provides you with a nice mechanism by which to lazy load images or "heavy" components.

Installation

yarn add react-virtual-container

Or, if you prefer npm:

npm install react-virtual-container

Example

In the example below you will note two virtual containers. As the viewport moves down the page it triggers each virtual container causing the associated component to render and replace their placeholder.

Example - Out Again

In this example we expand on the behaviour of our virtual containers by setting the inAndOut prop. With this prop enabled as the viewport moves away from the virtual containers the components will again be replaced by their placeholders. This can be useful for cases where the components being virtualised consume a heavy amount of CPU/memory resources.

Usage

This library follows the "render prop" pattern, allowing you to specify a render or children prop. The "render prop" will be called and have its result rendered when the virtual container is within proximity of the viewport.

By default the virtual container needs to be within "50vh" proximity of the viewport. This is configurable - see configuration. You could set it to a pixel value or any other standard CSS unit value.

In addition to the "render prop" a useful prop is placeholder; it allows you to provide a component which will be rendered by the virtual container until it is within proximity of the viewport. This allows you to avoid layout that jumps when the virtual container activates. The placeholder prop is optional, however, we do recommend using it where you expect content jumping to occur.

import React from 'react'
import VirtualContainer from 'react-virtual-container'

const Placeholder = () => <div>🙈</div>

export default function MyVirtualisedComponent() {
  return (
    <VirtualContainer placeholder={Placeholder}>
      {() => <div>🐵</div>}
    </VirtualContainer>
  )
}

Configuration

The virtual container component accepts the following props:

  • children (PropTypes.func)

    The "render prop" responsible for returning the elements you wish to render should the virtual container come within proximity of the viewport. You can alternatively use the render prop.

  • className (PropTypes.string, optional)

    A class to apply to the virtual container element.

    Note: when providing a style for your virtual container element you MUST ensure that you have a "position" value set. This is because we use a set of absolutely positioned elements by which to track the proximity.

  • el (PropTypes.string, default: "div")

    The type of element that the virtual container should render as.

    Your render prop results will render as children to this element.

  • inAndOut (PropTypes.bool, default: false)

    If you enable this prop, then your component will be removed (or replaced with the placeholder if one was defined) when the viewport moves out of proximity to the virtual container.

    This can be especially useful for component that heavily use CPU/memory resources.

  • offsetBottom (PropTypes.oneOfType([PropTypes.string, PropTypes.number]), default: "50vh")

    The proximity value that will trigger rendering of your "render prop" when the virtual container is within the specified distance relative to the bottom of the view port.

  • offsetTop (PropTypes.oneOfType([PropTypes.string, PropTypes.number]), default: "50vh")

    The proximity value that will trigger rendering of your "render prop" when the virtual container is within the specified distance relative to the top of the view port.

  • onChange (PropTypes.func)

    If provided, this callback function will be called any time the virtualisation value changes. It recieves a single boolean parameter, being true when virtualisation is active, and false when it is not.

  • optimistic (PropTypes.bool, default: false)

    If you set this then the placeholder will be rendered before the "render prop" whilst we determine if the virtual container is within proximity of the viewport. You should almost never use this.

  • placeholder (PropTypes.func)

    A placeholder component/function that will be rendered when the virtual container is not within proximity of the viewport. Useful to avoid your page jumping with new content being inserted (especially when scrolling from the bottom of the page up).

  • render (PropTypes.func)

    The "render prop" responsible for returning the elements you wish to render should the virtual container come within proximity of the viewport. You can alternatively use the children prop.

  • scrollableAncestor (PropTypes.any)

    When tracking proximity we use scroll positioning. Depending on the structure of your DOM you may want to explicitly define the element by which your scrolling is bound. For example this could be a value of "window" or a direct reference to a DOM node.

  • style (PropTypes.object)

    A style to provide to the virtual container element.

    Note: when providing a style for your virtual container element you MUST ensure that you have a "position" value set. This is because we use a set of absolutely positioned elements by which to track the proximity.

Tips and Tricks

Below are some useful tips for using this library effectively within your app.

Usage with Styled Components or Emotion

The VirtualContainer component produces an actual DOM element - a div by default, although this is configurable via the el prop.

What if you want to style the element via Styled Components or Emotion, two very popular CSS-in-JS libraries.

You can completely do so by wrapping the VirtualContainer with the style function. Styled Components / Emotion will then pass down a className to the VirtualContainer, which it supports as a prop. The className will be applied to the element.

We will update the example from earlier to do so.

import styled from 'react-emotion'
import VirtualContainer from 'react-virtual-container'

const StyledVirtualContainer = styled(VirtualContainer)`
  position: relative;
  height: 100px;
  background-color: pink;
`

export default function MyVirtualisedComponent() {
  return (
    //                        👇 you can still pass down configuration! woot!
    <StyledVirtualContainer inAndOut>
      {() => <div>🐵</div>}
    </StyledVirtualContainer>
  )
}

Awesome! This is a pretty powerful technique, and can aid in avoiding having to use a placeholder.

Note: when providing your own styled, please make sure you set a "position" style on your component. This is because internally we have some relatively positioned elements which are rendered as children in order to tracking of viewport proximity.