API Reference

During the development process, all APIs can be viewed in the code editor (e.g. VS Code) by going to their type declaration to view the specific declaration.

useLocalForageState

The protagonist of this package, it is very similar to useState (opens in a new tab) usage, Please use it together with LocalForageProvider .

// Normal state variable
const [state, setState] = useState(defaultValue)
 
// State variables with storage behavior
const [state, setState] = useLocalForageState('storage-key', { defaultValue })

If you want to delete record from store, you can use setState() or setState(undefined) .

Type Declarations

declare const useLocalForageState: <T>(
  key: string,
  options?: Options<T>,
) => readonly [T | undefined, (value?: SetState<T> | undefined) => void]
 
type SetStateValue<S> = (prevState?: S) => S
 
type SetState<S> = S | SetStateValue<S>
 
type GetDefaultValue<T> = () => T
 
interface Options<T> {
  defaultValue?: T | GetDefaultValue<T>
  serializer?: (value: T) => string
  deserializer?: (value: string) => T
  onError?: (error: unknown) => void
}

Examples

import React from 'react'
 
const defaultMessage = 'Hello~'
 
const BasicExample: React.FC = () => {
  const [message, setMessage] = useLocalForageState<string | undefined>(
    'use-local-forage-state-demo-1',
    {
      defaultValue: defaultMessage,
    },
  )
 
  return (
    <div className={cls.wrapper}>
      <Input
        value={message || ''}
        placeholder="Please enter some words..."
        onChange={(e) => setMessage(e.target.value)}
      />
 
      <Button variant="outline" onClick={() => setMessage(defaultMessage)}>
        Reset
      </Button>
 
      <Button variant="outline" onClick={() => setMessage(undefined)}>
        Clear
      </Button>
    </div>
  )
}

LocalForageProvider

By default, calling useLocalForageState hook directly will use the default configuration and instance of localForage.

If you want to specify the configuration and create the specified instance, you can use LocalForageProvider to wrap the business component.

Configuration

Pass your localForage configuration, which will be used to create localForage instances and memoize them in the context.

For localForage supported configurations, please consult the official documentation.

Settings API Config - localForage API

Type Declarations

declare const LocalForageProvider: React.FC<LocalForageProviderProps>
 
interface LocalForageProviderProps {
  config?: LocalForageOptions
  children: React.ReactNode
}
 
enum LocalForageDriverType {
  IndexedDB = 'asyncStorage',
  WebSQL = 'localStorageWrapper',
  LocalStorage = 'webSQLStorage',
}
 
interface LocalForageDbInstanceOptions {
  name?: string
  storeName?: string
}
 
interface LocalForageOptions extends LocalForageDbInstanceOptions {
  driver?: LocalForageDriverType | LocalForageDriverType[]
  size?: number
  version?: number
  description?: string
}

Examples

import React from 'react'
 
interface ContainerProps {
  children: React.ReactNode
}
 
const Container: React.FC<ContainerProps> = ({ children }) => {
  return (
    <LocalForageProvider
      // localForage configuration
      config={{
        name: 'react-forage-website',
        storeName: 'examples',
      }}
    >
      <div className="max-w-screen-md mx-auto">{children}</div>
    </LocalForageProvider>
  )
}

useLocalForageContext

With LocalForageProvider , the context information of the storage configuration can be obtained through useLocalForageContext Hook. Generally, there is no need to actively use it, but in some cases, such as if you want to dropdown IndexedDB, you can operate it through the instance of the context.

Drop Instance - localForage API

Type Declarations

declare const useLocalForageContext: () => LocalForageContextProps

Examples

import React from 'react'
 
const DropInstanceExample: React.FC = () => {
  const { localforage } = useLocalForageContext()
 
  return (
    <Button variant="outline" onClick={() => localforage.dropInstance()}>
      Drop Instance
    </Button>
  )
}

Getting Started