Skip to content
A lightweight and easily configurable promo bar in ES6.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A lightweight and easily configurable promo bar with support for expiration using localStorage.

~1.77kb gzipped


npm i promobar --save

Basic Usage

This library requires some markup and styles. By default, the promo bar is not shown. Once shown, it will continue to show until a user closes it. Once closed, the promo bar will not show for that user again until either the content has been updated, or the time interval specified in lifespan is reached.

import promobar from 'promobar'

const target = document.getElementById('promobar')

const promo = promobar(target, {
  content: document.getElementById('promoContent').innerHTML,
  lifespan: 1,
  resize: true,
  placeholder: () => /products|posts/.test(window.location.pathname),
  offsets: [
    [document.getElementById('header'), () => /\//.test(window.location.pathname)],
  close: [ document.getElementById('promoClose') ]


promobar(target[, {...configation}])

The constructor takes two params, and return an instance object with API methods attached.

  • target - the outer element of your promo bar
  • configuration
    • content - the text and/or markup that is the content of your promo bar type: string - default: document.getElementById('promoContent').innerHTML
    • lifespan - the number of days before the promo expires and is enabled again for the user type: number - default: 1
    • resize - to watch the height of the bar on resize and adjust offsets to match type: boolean - default: true
    • placeholder - inserts a placeholder element that displaces the site by the height of the promo bar. Pass a function that returns a boolean to conditionally use a placeholder type: function|boolean - default: true
    • close - an array of elements that, when clicked, should trigger the hide sequence of the promo bar type: array - default:'.js-promobarClose'))
    • offsets - an array of elements that need to be displaced when the promo bar is active. These elements will receive an attribute that is styled with transformY. type: array - default: []

API: Methods


Show the promo bar. If expired, bar will not show.


Hide the promo bar.


Hide and cache the data to prevent the bar from showing until it expires.



Attach event handlers

promobar.on('show', state => /* do stuff */)


If promo bar is expired, clear data and re-enable the promo bar. To show the bar after .reset(), call .show().



Return the promo bar's state object.


  active: true|false, // shown or not
  enabled: true|false, // expired or not
  height: 50px // height of `target` outer element


You can also run handlers by emitting events manually.



Promobar emits a few lifecycle events. All callbacks receive a state object.

  • show - when shown
  • hide - when hidden
  • update - when updated
  • disabled - when a user closes the bar

Markup and Styles

Please see lib/promobar.html and lib/promobar.scss for suggested markup and styles.

MIT License

You can’t perform that action at this time.