Awesome Open Source
Awesome Open Source

Bin Build Status

A tiny (< 1kb) localStorage and sessionStorage helper library.

It automatically parses objects and arrays into strings (and back). It also let's you validate and expire localStorage data after a set period of time.

Installation | API | Browser Compatibility | License

Want to learn how to write your own vanilla JS libraries? Check out my Vanilla JS Pocket Guides or join the Vanilla JS Academy and level-up as a web developer. 🚀


The CDN is the fastest and simplest way to get started, but you can use importable modules or a direct download if you’d prefer.

<!-- Get the latest major version -->
<script src="[email protected]/dist/bin.min.js"></script>

Bin uses semantic versioning. You can grab a major, minor, or patch version from the CDN with the @1.2.3 syntax. You can find all available versions under releases.

ES Modules

Bin also supports modern browsers and module bundlers (like Rollup, Webpack, Snowpack, and so on) using the ES modules import syntax. Use the .es version.

import Bin from '[email protected]/dist/';


You can also use NPM (or your favorite package manager). First, install with NPM.

npm install storagebinjs --save

Then import the package.

import Bin from 'storagebinjs';


If you use NodeJS, you can import bin using the require() method with the .cjs version.

let Bin = require('[email protected]/dist/bin.cjs.min.js');


If you use RequireJS, SystemJS, and other AMD formats, you can import bin with the .amd version.

requirejs(['[email protected]/dist/bin.amd.min.js'], function (Bin) {

Direct Download

You can download the files directly from GitHub.

Compiled and production-ready code can be found in the dist directory. The src directory contains development code.

<script src="path/to/bin.min.js"></script>


Before working with Bin, you need to instantiate a new instance. Pass in the ID you would like to use for your localStorage/sessionStorage data as an argument.

Bin defaults to localStorage. You can optionally pass in true as a second argument to use sessionStorage instead.

// Instantiate a new localStorage instance
var myBin = new Bin('myBinID');

// Instantiate a new sessionStorage instance
var myBinSession = new Bin('myBinSessionID', true);


Save data to storage.

Pass in your data as an argument. It can be an object, array, string, number—any valid JavaScript object type. Bin will automatically convert it to a string for storage.

// Store an object
	sandwich: 'turkey',
	drink: 'soda',
	chips: true

// Store an array

// Store a string
myBin.set('I love Cape Cod potato chips!');

// Store a number

If you would like your data to expire, pass in the amount of time in seconds that the data is good for.

// expires in one week
// 60 seconds x 60 minutes x 24 hours x 7 days
myBin.set('Temporary value', 60 * 60 * 24 * 7);


Get data from storage. You can optionally pass in a fallback to use if no data is found.

// Get data from storage

// Use a fallback object

// Use a fallback array

// Use a fallback string

// Use a fallback number

If the data has expired, it will be removed and null will be returned. To get the actual data event if it has expired, pass in true as a second argument.

myBin.get('Temporary value', true);


Check if data has expired based on the expiration you set when defining it.

// 1 hour

// 1 day

// 1 week

// 1 year

// 15 minutes

// 2 days


Remove data from storage. The instance will remain available, but the data will be wiped from localStorage/sessionStorage.


Browser Compatibility

Bin works in all modern browsers, and IE 8 and above.


The code is available under the MIT License.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,512,368
Javascript Library (1,853
Vanilla Javascript (1,187
Localstorage (972
Vanilla Js (877
Sessionstorage (166
Related Projects