usepref - React User Preferences

usepref is a React library that allows you to manage, update, and store user preferences and settings.

Note: The only part of the library that is not React-specific is provider and hook, which is just a thin wrapper around the storage provider. If anyone wants to split this library into a core and react-specific library, that would be awesome, otherwise I'm sure I'll end up doing it if I need it in a non-react project.

Features

• [x] Store & Sync User Preferences
• [x] React Context Provider
• [x] React Hook
• [ ] Sync across multiple storage interfaces
• [ ] Asynchronous storage interfaces
• [ ] IPC

Storage Interfaces

• [x] Local Storage
• [x] Memory Storage
• [ ] IndexedDB
• [ ] Async Storage
• [ ] IPC

Getting Started

Installation

npm install usepref

Usage

This library comes with multiple storage interfaces that implement the Storage API. You can use any of these or create your own.

PreferenceStorage

PreferenceStorage is the parent class that manages the user preferences and mutating the storage. To start, simply create a new instance of PreferenceStorage.

import {PreferenceStorage} from 'usepref';

const storage = new PreferenceStorage({key: 'my-key'});

If no storage prop is provided, a default storage interface will be used. The default storage interface used depends on the environment. If the window object is defined, the default storage interface will be localStorage. Otherwise, it will be MemoryStorage.

You can provide your own storage interface by passing it to the PreferenceStorage constructor as follows:

import { PreferenceStorage } from 'usepref';
import { MemoryStorage } from 'usepref/storage/memory';

const storage = new PreferenceStorage({
  key: 'my-key',
  storage: new MemoryStorage(),
});

PreferencesProvider

The PreferencesProvider is a React context provider that provides the PreferenceStorage instance to its children.

import { PreferencesProvider } from 'usepref';

function App() {
  return (
    <PreferencesProvider>
      <MyApp/>
    </PreferencesProvider>
  );
}

usePreferences

The usePreferences hook a getter and setter for the PreferenceStorage instance.

Note: You can also use usePref() instead of usePreferences(), it's simply a shorter alias.

import { usePreferences } from 'usepref';

function MyComponent() {
  const { getItem } = usePreferences();

  return <div>{getItem('my-key')}</div>;
}

import { usePreferences } from 'usepref';

function MyComponent() {
  const { getItem, setItem } = usePreferences();

  return <Switch checked={getItem('my-key')} onChecked={(value) => setItem('my-key', value)} />;
}

Storage Interfaces

LocalStorage

The LocalStorage interface uses the Web API's localStorage.

MemoryStorage

The MemoryStorage interface uses an in-memory object to store the user preferences. See storage/memory.ts.

Contributing

New Storage Interfaces

New storage interfaces can be added by creating a new class that implements the Storage API. See storage/memory.ts for an example. If you want to add a new storage interface, go for it!