💾 Offline storage, improved. Wraps IndexedDB, WebSQL, or localStorage using a simple but powerful API.
JavaScript HTML TypeScript
Latest commit d9cbb37 Jan 19, 2017 @thgreasi thgreasi committed on GitHub docs(api): fix jsdiddle localforage.js urls
Failed to load latest commit information.
dist chore: add dist returning config's setDriver Promise Dec 19, 2016
docs docs(api): fix jsdiddle localforage.js urls Jan 19, 2017
examples fix(examples): fix requirejs example May 26, 2015
src feat: return config's setDriver Promise Dec 19, 2016
test feat: return config's setDriver Promise Dec 19, 2016
typing-tests feat(typings): update from DefinitelyTyped & add ready() (#637) Dec 20, 2016
typings feat(typings): update from DefinitelyTyped & add ready() (#637) Dec 20, 2016
.babelrc chore(localforage): promise -> lie, use ES6 modules Apr 25, 2016
.babelrc-umd chore(localforage): promise -> lie, use ES6 modules Apr 25, 2016
.gitignore test(webpack): add webpack bundling tests Aug 11, 2015
.jscsrc refactor(localforage): use es6 class object Aug 1, 2015
.jshintrc fix(localForage): support running inside web workers Aug 1, 2015
.travis.yml Update Travis URL and push to activate travis Jul 10, 2016
CHANGELOG.md Update Changelog (fix #574) Jun 7, 2016
CONTRIBUTING.md docs(CONTRIBUTING): add codepen example as basis for issues May 22, 2016
Gruntfile.js chore: fix wrong URL in dist BANNER (#638) Dec 21, 2016
LICENSE Fix license/copyright information Mar 9, 2014
README.md docs(README): update notice about using with webpack (#639) Dec 31, 2016
bower.json Release version 1.4.3 Oct 6, 2016
component.json Release version 1.4.3 Oct 6, 2016
contribute.json Add a contribute.json file Apr 19, 2015
package.json feat: add TypeScript typings (#611) Oct 23, 2016



Build Status NPM version Dependency Status npm

localForage is a fast and simple storage library for JavaScript. localForage improves the offline experience of your web app by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API.

localForage uses localStorage in browsers with no IndexedDB or WebSQL support. See the wiki for detailed compatibility info.

To use localForage, just drop a single JavaScript file into your page:

<script src="localforage.js"></script>
<script>localforage.getItem('something', myCallback);</script>

Download the latest localForage from GitHub, or install with npm:

npm install localforage

or bower:

bower install localforage

localForage is compatible with browserify.


Lost? Need help? Try the localForage API documentation.

If you're stuck using the library, running the tests, or want to contribute to localForage, you can visit irc.freenode.net and head to the #localforage channel to ask questions about localForage.

The best person to ask about localForage is tofumatt, who is usually online from 8am-8pm GMT (London Time).

How to use localForage

Callbacks vs Promises

Because localForage uses async storage, it has an async API. It's otherwise exactly the same as the localStorage API.

localForage has a dual API that allows you to either use Node-style callbacks or Promises. If you are unsure which one is right for you, it's recommended to use Promises.

Here's an example of the Node-style callback form:

localforage.setItem('key', 'value', function (err) {
  // if err is non-null, we got an error
  localforage.getItem('key', function (err, value) {
    // if err is non-null, we got an error. otherwise, value is the value 

And the Promise form:

localforage.setItem('key', 'value').then(function () {
  return localforage.getItem('key');
}).then(function (value) {
  // we got our value
}).catch(function (err) {
  // we got an error

For more examples, please visit the API docs.

Storing Blobs, TypedArrays, and other JS objects

You can store any type in localForage; you aren't limited to strings like in localStorage. Even if localStorage is your storage backend, localForage automatically does JSON.parse() and JSON.stringify() when getting/setting values.

localForage supports storing all native JS objects that can be serialized to JSON, as well as ArrayBuffers, Blobs, and TypedArrays. Check the API docs for a full list of types supported by localForage.

All types are supported in every storage backend, though storage limits in localStorage make storing many large Blobs impossible.


You can set database information with the config() method. Available options are driver, name, storeName, version, size, and description.


    driver      : localforage.WEBSQL, // Force WebSQL; same as using setDriver()
    name        : 'myApp',
    version     : 1.0,
    size        : 4980736, // Size of database, in bytes. WebSQL-only for now.
    storeName   : 'keyvaluepairs', // Should be alphanumeric, with underscores.
    description : 'some description'

Note: you must call config() before you interact with your data. This means calling config() before using getItem(), setItem(), removeItem(), clear(), key(), keys() or length().

Multiple instances

You can create multiple instances of localForage that point to different stores using createInstance. All the configuration options used by config are supported.

var store = localforage.createInstance({
  name: "nameHere"

var otherStore = localforage.createInstance({
  name: "otherName"

// Setting the key on one of these doesn't affect the other.
store.setItem("key", "value");
otherStore.setItem("key", "value2");


You can use localForage with RequireJS:

define(['localforage'], function(localforage) {
    // As a callback:
    localforage.setItem('mykey', 'myvalue', console.log);

    // With a Promise:
    localforage.setItem('mykey', 'myvalue').then(console.log);

Browserify and Webpack

localForage 1.3+ works with both Browserify and Webpack. If you're using an earlier version of localForage and are having issues with Browserify or Webpack, please upgrade to 1.3.0 or above.

Webpack will emit a warning about using a prebuilt javascript file which is fine. If you want to remove the warning you should exclude localforage from being parsed by webpack using the following conf :

module: {
  noParse: /node_modules\/localforage\/dist\/localforage.js/,
  loaders: [...],


If you have the allowSyntheticDefaultImports compiler option set to true in your tsconfig.json (supported in TypeScript v1.8+), you should use:

import localForage from "localforage";

Otherwise you should use one of the following:

import * as localForage from "localforage";
// or, in case that the typescript version that you are using
// doesn't support ES6 style imports for UMD modules like localForage
import localForage = require("localforage");

Framework Support

If you use a framework listed, there's a localForage storage driver for the models in your framework so you can store data offline with localForage. We have drivers for the following frameworks:

If you have a driver you'd like listed, please open an issue to have it added to this list.

Custom Drivers

You can create your own driver if you want; see the defineDriver API docs.

There is a list of custom drivers on the wiki.

Working on localForage

You'll need node/npm and bower.

To work on localForage, you should start by forking it and installing its dependencies. Replace USERNAME with your GitHub username and run the following:

# Install bower globally if you don't have it:
npm install -g bower

# Replace USERNAME with your GitHub username:
git clone git@github.com:USERNAME/localForage.git
cd localForage
npm install
bower install

Omitting the bower dependencies will cause the tests to fail!

Running Tests

You need PhantomJS installed to run local tests. Run npm test (or, directly: grunt test). Your code must also pass the linter.

localForage is designed to run in the browser, so the tests explicitly require a browser environment. Local tests are run on a headless WebKit (using PhantomJS).

When you submit a pull request, tests will be run against all browsers that localForage supports on Travis CI using Sauce Labs.


This program is free software; it is distributed under an Apache License.

Copyright (c) 2013-2016 Mozilla (Contributors).