React List Provider

Use Context to save lists of whatever you want, then access them anywhere in your componpent tree.

index.js

import { ListProvider } from 'react-list-provider';
import App from './app';
import ReactDOM from 'react-dom';
 
ReactDOM.render(
  <ListProvider name="notifications">
    <App />
  </ListProvider>,
  document.body
);

app.js

const { useList } = require('react-list-provider');
 
export const App = () => {
  const { addItem, items } = useList({ name: 'notifications' });
 
  return (
    <div>
      {items.map((item) => (
        <div>Notification: {item.message}</div>
      ))}
      Example application
      <button
        onClick={() => addItem({ id: Date.now().toString(), message: 'Hi' })}
      >
        Say hi
      </button>
    </div>
  );
};

Installation

yarn add react-list-provider

or, for npm:

npm install --save react-list-provider

API

import { ListProvider, ListConsumer, useList, withListManager } from 'react-list-provider';

<ListProvider>

A React Context Provider for an instance of a list of items.

<ListProvider name="notifications" keyBy="id">
  <App />
</ListProvider>

Props

Prop	isRequired	Description
name	✅	A unique name used to identify the list. Must match a corresponding usage of useList/withListManager/ListConsumer
keyBy		Enforce uniqueness by setting a key to use when adding items. For example, setting 'id' will ensure all added items have a unique 'id' field. If omitted, no uniqueness will be enforced, and only items/addItems/clearItems methods are exposed on the context.

List Methods

Each of useList/withListManager/ListConsumer return a context object which contains the following keys:

	Type	Description
items	Array<Item>	The list items as added with addItem
addItem	Function(<Item>): void	Add an individual item to the list. If the <ListProvider> has keyBy set, the item passed to addItem must contain that field.
clearItems	Function(): void	Remove all items from the list.
updateItem*	Function(key, <Item>): void	Update a single item in the list. Performs a shallow merge.
removeItem *	Function(key): void	Remove a single item from the list.
removeItems *	Function(key): void	Remove multiple items from the list.
hasItem *	Function(key): Boolean	Check if an item in the list has the given key.
getItem *	Function(): <Item>	Retrieve the item in the list with the given key (or undefined).

* Only available when keyBy is set on the <ListProvider>

<ListConsumer>

A React Context Consumer, used to access the list methods.

<ListConsumer name="notifications">
  {(context) => {
    // context.items, context.addItem, ...etc
    return <App />;
  }}
</ListConsumer>

Props

Prop	isRequired	Description
name	✅	A unique name used to identify the list. Must match a corresponding usage of <ListProvider>

useList(config)

A React Hook, used to access the list methods.

const Component = () => {
  const { items, addItem, ...etc } = useList({ name: 'notifications' });
  return <App />;
};

config

	isRequired	Description
name	✅	A unique name used to identify the list. Must match a corresponding usage of <ListProvider>

withListManager(Component, config)

Creates a React Higher Order Component which injects a prop named listManager; an object containing the list methods.

const Component = ({ listManager }) => {
  // listManager.items, listManager.addItem, etc...
  return <App />;
};
 
const ComponentWithList = withListManager(Component, { name: 'notifications' });

Component

The existing React component to inject the prop listManager into.

config

	isRequired	Description
name	✅	A unique name used to identify the list. Must match a corresponding usage of <ListProvider>

Nested Providers

It's possible to nest <ListProvider>s, enabling multiple lists to co-exists.

Nested Providers must be given a unique name to differentiate them:

import { ListProvider, ListConsumer } from 'react-list-provider';
const App = () => (
  <ListProvider name="accounts">
    <ListProvider name="notifications">
      <ListConsumer name="notifications">
        {({ addItem }) => (
          <button onClick={() => addItem('Hello')}>Add Notification</button>
        )}
      </ListConsumer>
      <ListConsumer name="accounts">
        {({ addItem }) => (
          <button onClick={() => addItem('Jess')}>Add Account</button>
        )}
      </ListConsumer>
    </ListProvider>
  </ListProvider>
);