Skip to content
Add a visible countdown to your views.
Branch: master
Clone or download
Pull request Compare This branch is 1 commit ahead of shlub:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Travis Gem Version Code Climate Test Coverage Inline docs

Gem | Source | Documentation

Place a countdown element on your view! It'll be updated by JavaScript.

Use the framework of your choice. A generator is only available for Rails, though.


Add this line to your application's Gemfile:

gem 'bottle_rocket'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bottle_rocket

Rails 3.1 or greater (with asset pipeline enabled)

Require the javascript file in app/assets/javascripts/application.js:

//= require bottle_rocket

Rails 3.0 (or greater with asset pipeline disabled)

Run the generator:

rails generate bottle_rocket:install

Running the generator will copy 'bottle_rocket.js' over to the public\javascripts directory. Be sure to add bottle_rocket.js to your layout file:

<%= javascript_include_tag 'bottle_rocket' %>

To make Javascript updates work on other frameworks download the file from 'vendor/assets' manually and place it in the corresponding directory.


 <%= countdown to: + 28.hours %>

results in a countdown like this:

1d 03 h 59m 59s

or to count down from another time than now:

 <%= countdown to: - 2.months, from: Time.parse '2012-09-27 01:07:00' %>

The generated html looks like this:

<div class="countdown">
  <span class="unit days">
    <span class="amount-1">1</span>
    <span class="separator">d</span>
  <span class="unit hours">
    <span class="amount-0">0</span>
    <span class="amount-3">3</span>
    <span class="separator">h</span>
  <span class="unit minutes">
    <span class="amount-5">5</span>
    <span class="amount-9">9</span>
    <span class="separator">m</span>
  <span class="unit seconds">
    <span class="amount-5">5</span>
    <span class="amount-9">9</span>
    <span class="separator">s</span>


Select which time units should be displayed. The given order affects the output of the result.

Available keys are:

:days, :hours, :minutes, :seconds, :milliseconds

Default is

[:days, :hours, :minutes, :seconds]

Example with selected units using default options:

 <%= countdown to: + 2.hours, units: [:minutes, :seconds] %>

results in a countdown like this:

59m 59s


When you want to modify a unit using options supply the unit as a Hash. Additional units supplied as symbols are not affected.


Define how different time units are separated from each other.

Defaults to:

millenniums:  'MN'
centuries:    'C'
decades:      'D'
years:        'Y'
months:       'M'
weeks:        'w'
days:         'd'
hours:        'h'
minutes:      'm'
seconds:      's'
milliseconds: 'ms'
microseconds: 'µs'
nanoseconds:  'ns'

Example to overwrite the 'days' separator:

<%= countdown to: + 2.months, units: [{ days: { separator: { title: 'T' } } }] %>

results in a countdown like this:

61 T

To singularize separators on '1' and '-1' pass an additional 'singular' option:

<%= countdown to: +, units: [{ days: { separator: { title: 'days', singular: 'day' } } }] %>

results in a countdown like this:

1 day


You can add leading zeroes to units. Nice to have when using a 'clock-like' countdown.

Defaults to



 <%= countdown to: + 124.minutes, units: [{ hours: { separator: { title: ':' }, leading_zeroes: true } }, { minutes: { separator: { title: ':' }, leading_zeroes: true } }, { seconds: { leading_zeroes: true } }] %>

results in a countdown like this:



Define how often the countdown should be updated via Javascript.

Possible steps are:

:milliseconds, :seconds, :minutes, :hours, :days

Defaults to the smallest unit value specified (uses seconds when no steps and no units are specified).


<%= countdown to: +, steps: :minutes %>

will update the countdown every minute.


For a reverse countdown starting at 00:00:00 use the countup method using the same options:

 <%= countup from: to: + 1.hour %>


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
You can’t perform that action at this time.