TypeScript icon, indicating that this package has built-in type declarations

    1.4.1 • Public • Published

    action-release codecov


    This library helps on one of the trickier parts of writing React components: How to render on ansynchronously fetched data and cache such data effectively.


    $ yarn add react-idb-cache


    import { useCached } from 'react-idb-cache'
    function MyComponent() {
      const { get, set } = useCached()
      // Get value from IndexedDB if it exists - the state will be updated if a value is received
      const value = get('indexKeyForValue')
      // Load a value from an API endpoint if it does not exist in the cache or IndexedDB
      const otherValue = get('indexKeyForOtherValue', () => someRequest().then(({theRequiredValue, someOtherValue}) => {
          // set the value in state and IndexedDB
          set('indexKeyForOtherValue', theRequiredValue, {someMetaField: 123})
      // The component can render without blocking anything.
      // It will be updated once values are available.
      return <div>


      const api = useCached({dbName: 'my-database', storeName: 'my-store'})

    Per default the hook uses a store keyval in database Cached.


    The hooks cache values in a shared context. You can isolate some of the components so the cache is removed with the components by wrapping them with a Provider.

      import { CacheProvider, useCached } from 'react-idb-cache'
      function MyWrapperComponent() {
        return <CacheProvider>
      function MyComponentA() {
        const api = useCached()
      function MyComponentB() {
        const api = useCached()

    You can also make a component use its own local cache:

      const api = useCached({context: false})


    This library defaults to use IndexedDB as device level cache per idb-keyval.

    You can switch out the driver used for local cache in the context of a CacheProvider.

    import { CacheProvider } from 'react-idb-cache'
    import NullDB from 'react-idb-cache/driver/NullDB'
    function MyWrapperComponent() {
      return <CacheProvider dbDriverFactory={NullDB}>

    Supplying your own driver is possible but considered experimental as the DBDriver API might be subject to change in minor versions. If you'd like to add another local DB implementation, PRs are very much welcome!


    Get a single value

      const { get } = useCached()

    In TypeScript you can declare the data type you get:

      const { get } = useCached()
      get<string, 'data', number>('indexKeyForValue') // is expected to be a number

    Get multiple values

      const { get } = useCached()
      get(['keyOne', 'keyTwo'])
      // returns a record of key-value pairs
        keyOne: 'foo',
        keyTwo: 'bar',

    Load data from the backend

      const { get } = useCached()
      get(['keyOne', 'keyTwo'], myLoader)
      // if the cache/idb has a value for some of the keys, they are returned
        keyOne: 'foo',
        keyTwo: undefined,

    The loader is called - for multiple key requests with an array of missing keys - and should return a Promise that should resolve once the transaction is done.

    Reload outdated entries


    You can discard entries from cache/idb per expire callback. If a loader is present, it will be called with the missing keys and those keys for which expire returned true.

      const { get } = useCached()
      get('someKey', myLoader, ({data, meta}) => meta.someMetaField > 123)

    You can discard entries from cache/idb that are older than expire milliseconds. If a loader is present, it will be called with the missing keys and those keys for which expire returned true.

      const { get } = useCached()
      get('someKey', myLoader, 5000) // discard cached entry if is older that 5 seconds

    Get meta data

      const { get } = useCached()
      get('indexKeyForValue', undefined, undefined, 'obj')
      // returns the cached data alongside the meta
      // also includes the result of the validation according to expire parameter
        data: 'foo',
        meta: {
          date: '2021-01-15T18:21:00.152Z',
        valid: true,

    Automatic rerender

    If a component calls get() for some keys it subscribes to further changes to that entry. When this or any other components alters that entry through one of the writing methods described below, the component automatically rerenders.


    Set a single value

      const { set } = useCached()
      set('someKey', 'someValue')

    The value can be anything that can be stored into IndexedDB.

    You can also store some meta data for the entry.

      const { set } = useCached()
      set('someKey', 'someValue', {someMetaKey: new Date()})

    Set multiple values

      const { set } = useCached()
        keyOne: 'someValue',
        keyTwo: 'otherValue',
      }, {
        keyOne: {
          someMetaKey: 'metaValue',

    Unset values

    You can also unset values in bulk action.

      const { set } = useCached()
        keyOne: 'someValue',
        keyTwo: 'whatever',
      }, {
        keyTwo: null, // this will remove the entry for 'keyTwo'

    Skip idb

    You can set values in the react cache but not in IndexedDB:

      const { set } = useCached()
      set('foo', 'bar', undefined, {skipIdb: true})
      set({foo: 'bar'}, undefined, {skipIdb: true})


      const { del } = useCached()


    Whole cache and idb-store

      const { clear } = useCached()

    Filter entries per callback

    Deletes some data from cache and IndexedDB.

      const { clear } = useCached()
      clear(({data, meta}) => meta.someMetaField > 2) // this will remove all entries with meta.someMetaField > 2


    You can get all entries cached in context or local DB:

      const { entries } = useCached()
      entries().map([key, data] => {
        // ...

    The component will automatically rerender if an entry in the cache is updated/deleted.


    npm i react-idb-cache

    DownloadsWeekly Downloads






    Unpacked Size

    60.4 kB

    Total Files


    Last publish


    • ph.fritsche