I am happy to announce that after over 2 years of development, React Floodgate is releasing today under version 1.0.0!
Floodgate is a "load more" component for React.js that takes the complexity of managing and updating queued data and turns it into an intuitive experience. It takes a minimalist approach to configuration: with only 1 required prop and using the render prop pattern, developers have precise control about how much of the available data is rendered, and the manner in which it is rendered.
For a quick peek into a barebones implementation of Floodgate, check out the example below.
import React from "react";
import Floodgate from "react-floodgate";
export default function LoadMore() {
const albums = ["For Emma, Forever Ago", "Bon Iver, Bon Iver", "22 a million", "i,i"];
return (
<Floodgate data={albums} initial={1} increment={1}>
{({ items, loadNext, loadComplete }) => (
<React.Fragment>
<h1>Bon Iver Albums</h1>
<ol>
{items.map(album => <li>{album}</li>)}
</ol>
<button onClick={loadNext} disabled={loadComplete}>Add Album</button>
</React.Fragment>
)}
</Floodgate>
);
}
That is all it takes to create a working "load more" component!
To get started using Floodgate today, install it into your React project
# using npm
npm i react-floodgate
# using yarn
yarn add react-floodgate
Features
While Floodgate is minimalistic, it can be incredibly powerful, depending on how its features are leveraged in concert with other components and patterns. Get a brief introduction to what Floodgate can do below; check out the README file to get a deeper understanding and technical details.
📊 Consume any type of data
Floodgate's data prop only requires that an array is passed to it; that array can be anything, including empty! Strings, parsed JSON objects, React components, even JavaScript functions can be passed in; remember that Floodgate leaves the rendering and implementation of these items up to the developer.
Values like data={["hello", "world"]}, data={[<li>Eggs</li>, <li>cereal</li>, <li>paper towels</li>]}, data={[]} are all valid to be passed to Floodgate. As a note, while Floodgate doesn't care what type(s) of item makes up the array, it is recommended to make sure the type is uniform amongst all the array elements.
🔢 Determine the quantity of items to render
Tell Floodgate how many items from the data array should be loaded on the initial render with the initial prop. The increment prop handles how many items are loaded on subsequent calls to loadNext() in the render prop function.
🎛 Manage props from a parent component
By utilizing React's lifecycle methods and custom callback props, Floodgate's props can be entirely managed by a parent component's state, allowing the instance's data to be asynchronously updated or end-users to have more control over how many items are loaded. I call this the Controlled Floodgate pattern.
☎️ Handle events with event-driven callback props
The render prop function exposes a number of Floodgate methods to be called by its children components; namely, those are loadNext, loadAll, reset, and exportState. When these methods are called, Floodgate calls the function provided to the on[MethodName] prop, if one is provided.
🔮 Leverage the Context API
Floodgate utilizes the React's Context API as of v0.6.0, preventing the need for developers to pass down methods exposed in the render prop to wherever they are needed using the FloodgateContext export.
🛠 Built with TypeScript
Floodgate is built with Typescript, and is distributed with a types definition file for an enhanced developer experience.
Examples
For a better understanding of how Floodgate works, check out this Codesandbox.io examples folder. Here you can see the way the code is setup, as well as the resulting app that an end-user would interact with.
One real-life example of Floodgate in use is on my personal site's writing page.
Roadmap
This project is pretty green, but there are some features that I will be planning to implement in the near future, in addition to solving issues and addressing immediate needs of Floodgate users:
- Error Boundaries
- Hooks support (
useFloodgate) - Documentation website
- Improve README, especially "Contributors" section
Explore on GitHub
Floodgate is available on GitHub at geoffdavis92/react-floodgate. There, you can view the component's README, examine source files, file an issue, take a look at open projects, and do all the usual GitHub repo things.
What do you think?
Do you like Floodgate? Is your app in desperate need of this component? Let me know by tweeting me about it!
🎉 Happy developing! 🎉