Soon

Documentation

Quick setup

You can configure soon manually or use the visual builder. The visual builder is the adviced method as it's way easier to finetune your countdown component that way.

If you're using the visual builder extras/builder.html or are going to copy paste HTML from this document you can use the extras/setup.html template as a starting point.

The easiest way to manually work with Soon is by writing HTML, once Soon runs it will pickup all HTML nodes with the .soon class and turn them into counters. If you want more control you can use jQuery or the Soon API to create your counters manually.

Setting a date

Add an HTML node to your website with the class .soon like this <div class="soon"></div>. Soon will pick it up immidiately and render a simple clock. This is the default state and it quickly tells you everything is working.

You can turn the clock into a countdown by adding the data-due attribute. If you want to count up from a date, set the data-since attribute instead.

The data-due and data-since attributes can be set in ISO 8601 format. This may sound adventurous but don't worry it's actually pretty easy.

A couple of example date are shown below:

  • 2016 counts to a certain year.
  • 2016-11 counts to a specific month, in this case November.
  • 2016-11-25 counts to a specific day.
  • 2016-11-25T22:10 counts to a specific time.

For cases where you need to set a timezone just add it after the time +05:00.

  • 2016-11-25T22:10+05:00

The data-due attribute also accepts two other ways of defining a due date. You can can set it to count down a fixed amount of time from page load.

  • in 10 seconds
  • in 5 minutes
  • in 6 hours
  • in 1 hour

Or you can count down to a certain time on a certain day.

  • at 12 12 o'clock each day
  • at 9 9 o'clock each day
  • monday at 10:30 monday at 10:30
  • at 15:10:05 each day at 15:10:05
  • sunday at 10 zone +01:00 10 o'clock on sunday with fixed timezone

Prepend reset if you want to reset the counter when it reaches zero.

  • reset monday at 10:30 will count to next monday at 10:30 once it's monday 10:30:01.

Below you can see Soon's default state (the current time) and what happens after you add a due date or a since date.

from a clock to counting down to 2016
<!-- no date set -->
<div class="soon"></div>

<!-- due date set -->
<div class="soon" data-due="2017"></div>

<!-- due date set -->
<div class="soon" data-due="in 5 minutes"></div>

<!-- due date set -->
<div class="soon" data-due="at 23:30"></div>

<!-- due date set -->
<div class="soon" data-due="monday at 12:00"></div>

<!-- due date set -->
<div class="soon" data-due="reset monday at 12:00"></div>

<!-- since date set -->
<div class="soon" data-since="2014"></div>

Using jQuery

Soon can be used with jQuery, but this is not a requirement.

If you want to use jQuery you can create Soon counters using the script shown in the codeblock below. Read more about jQuery methods in the Create section of the documentation.

how to use jQuery
<script>
$(document).ready(function() {

    // create a simple soon counter on the supplied element
    $(".your-counter").soon().create({
        due:"2017",
        layout:"group"
    });

    // create a more advanced counter
    $(".your-advanced-counter").soon().create({
        due:"2017-11-25",
        layout:"group tight",
        face:"flip color-light corners-sharp shadow-soft",
        separateChars:false,
        eventComplete:function(){ alert("done!"); }
    });

});
</script>

Picking a face

You can pick different ways to present your counter by setting the data-face attribute. By default Soon uses text. After choosing a face type the specific type can then be customized to your liking with additional animation and visual options. We'll get to that in the Making it visually unique topic.

Currently available face types:

  • text default
  • slot animates changes between characters, you can pick from a diverse set of animations and animation directions.
  • flip a beautiful flip counter, available in black and white.
  • matrix a dot matrix counter, real old school.
different clock faces
<!-- text -->
<div class="soon" data-due="2017"
    data-face="slot">
</div>

<!-- slot -->
<div class="soon"
    data-due="2017"
    data-face="slot">
</div>

<!-- flip -->
<div class="soon"
    data-due="2017"
    data-face="flip">
</div>

<!-- matrix -->
<div class="soon"
     data-due="2017"
     data-face="matrix">
</div>

Adding a visual

To spice up your counter you can pick from two different visuals. A ring and a fill visual. Both show the individual progress for each group of values. As with the views, these two can also be customized, this we'll dive into in the Making it visually unique topic.

different visuals
<!-- the ring visual -->
<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="ring">
</div>

<!-- the fill visual -->
<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill">
</div>

Setting the counter format

There's a whole set of options to configure the way Soon formats the countdown.

Date format

You can set the date format by supplying the data-format attribute. By default it renders days, hours, minutes and seconds. You can also have it show years, months, weeks and milliseconds by using the y, M, w and ms formatters.

different date formats
<!-- only show days -->
<div class="soon" data-due="2017" data-format="d"></div>

<!-- hours and minutes -->
<div class="soon" data-due="2017" data-format="h,m"></div>

<!-- only seconds -->
<div class="soon" data-due="2017" data-format="s"></div>

<!-- milliseconds -->
<div class="soon" data-due="2017" data-format="h,m,s,ms"></div>

<!-- show years -->
<div class="soon" data-due="2018" data-format="y,d,h,m,s"></div>

Cascade values

By default Soon cascades values. This means that if you disable the day in the data-format attribute the amount of days will be shown as hours. Sometimes you may not want to do this, in that case you can set the data-cascade attribute to false.

setting value cascade
<!-- only show days -->
<div class="soon" data-due="2017" data-format="d"></div>

<!-- hours and minutes -->
<div class="soon" data-due="2017" data-format="h,m,s"></div>

<!-- hours and minutes, no cascade -->
<div class="soon" data-due="2017" data-format="h,m,s" data-cascade="false"></div>

With cascade

Without cascade

Character separation

Charachter separation allows you to control if Soon will put each character in it's own slot. See below for an example using the flip face.

splitting characters
<div class="soon"
     data-due="2017"
     data-face="flip">
</div>

<div class="soon"
     data-due="2017"
     data-separate-chars="false"
     data-face="flip">
</div>

Separator type

What if you want to use a : or . between character groups? Use the data-separator property. Any value set will be put between the character groups.

separator character
<div class="soon"
     data-separator="/"
     data-due="2017"
     data-face="text">
</div>

<div class="soon"
     data-separator=":"
     data-due="2017"
     data-face="text">
</div>

Label names

Use the attributes shown in the example HTML to control the names shown in the labels. You can supply a single value if you're only gowing to use plurals. If you intend to use singular labels you can supply two values by separating them with a comma.

control label names
<div class="soon"
     data-due="2017"
     data-labels-days="Dia,Dias"
     data-labels-hours="Hora,Horas"
     data-labels-minutes="Minuto,Minutos"
     data-labels-seconds="Segundo,Segundos">
</div>

Singular labels

Controls the use of singular and plural terms in labels. If set to true Soon will use singulars when a counter reaches 1. The default state is false.

toggle plurals
<div class="soon"
     data-due="2017"
     data-singular="true"
     data-face="slot">
</div>

Value padding

Allows you to put zeros in front of values. Or disable padding altogether by setting the data-padding attribute to false.

padding values
<!-- no padding -->
<div class="soon"
     data-padding="false">
</div>

<!-- minute and second padding -->
<div class="soon"
     data-padding-minutes="00"
     data-padding-seconds="00">
</div>

Making it visually unique

Each type of face comes with a set of configuration options to make it unique for your use case.

Generic options

The following options can be applied to all counter types

Layout

Add a data-layout attribute to control the counter layout. Default layout is group, the other option is inline which puts the counter on a single row.

as a row or grouped
<div class="soon"
     data-due="2017"
     data-layout="line">
</div>
<div class="soon"
     data-due="2017"
     data-layout="group">
</div>

Scale

Soon will automatically scale the counter to fit the parent container. You can control the maximum size of the counter by setting the data-scale-max attribute to xxl, xl, l, m (default value when not set), s, xs and xxs. You can set the value to fill if you want Soon to take up all available space.

If the counter does not fit Soon will automatically hide unused groups. If for instance the format is set to "year, day, hour, minute" and the years are at 0, Soon will hide the year group on small containers. If all groups contain values Soon will hide values from the right side, so minutes will be hidden. You can prevent the later behaviour by setting data-scale-hide to empty. If you don't want to allow hiding of any groups set the value to none.

Spacing

Add the values overlap, adjacent, tight or spacey to control the room between the counter groups when in group layout mode.

If labels start overlapping you can adjust this using the label size configuration below.

control spacing between groups
<div class="soon"
     data-due="2017"
     data-layout="spacey">
</div>
<div class="soon"
     data-due="2017">
</div>
<div class="soon"
     data-due="2017"
     data-layout="tight">
</div>
<div class="soon"
     data-due="2017"
     data-layout="adjacent">
</div>
<div class="soon"
     data-due="2017"
     data-layout="overlap">
</div>

Labels

Control the way labels are positioned by adding the attribute values label-hidden, label-small and label-big. If you want to put the labels above the numbers use the label-above value.

Control label casing with the label-uppercase and label-lowercase attributes.

Combine these values with the spacing parameters if labels overlap.

as a row or grouped
<div class="soon"
     data-due="2017"
     data-layout="label-hidden">
</div>

<div class="soon"
     data-due="2017"
     data-layout="label-small">
</div>

<div class="soon"
     data-due="2017">
</div>

<div class="soon"
     data-due="2017"
     data-layout="label-big">
</div>

<div class="soon"
     data-due="2017"
     data-layout="label-above">
</div>

Reflection

You can have the counter reflect by adding the data-reflect attribute and setting the value to true.

adding a reflection
<div class="soon"
     data-due="2017"
     data-layout="label-hidden"
     data-reflect="true">
</div>

Face specific options

Flip

The flip counter can be configured by adding the following parameters to the data-face attribute.

  • Control color with color-light or color-dark.
  • Alter the shadow style with shadow-hard or shadow-soft.
  • Speed up animations with the fast or faster attribute.
  • Set corner sharpness with the corners-sharp and corners-round values.

Of course you can also fine tune all these values using CSS. See the presets page for some examples.

different flip styles
<div class="soon"
     data-due="2017" data-face="flip color-light corners-round shadow-soft">
</div>

<div class="soon"
     data-due="2017" data-face="flip color-dark corners-sharp shadow-hard fast">
</div>

Slot

The slot counter can be configured with the following parameters.

  • Control shadow style with shadow-hard, shadow-soft or glow.
  • Set animation type with the following values fade, slide, rotate, roll and doctor.
  • Set animation direction for slide and roll by adding up, down, left or right.
  • Set animation direction for rotate with left and right.
  • Control animation speed with the fast or faster attribute.

Of course you can also fine tune all these values using CSS. See the presets page for some examples.

different slot styles
<div class="soon"
     data-due="2017"
     data-face="slot shadow-soft fade fast">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot rotate left">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot roll down fast">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot doctor">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot roll left">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot shadow-hard slide up">
</div>

Matrix

The dot matrix visual can be tweaked as well.

  • You can control the spacing between the dots with the spacey and tight values.
  • Control the resolution with the 5x7 or 3x5 settings.
  • Add a shadow or glow with shadow-soft, shadow-hard and glow.
  • Change the shape of the dots with dot-round and dot-square.
  • Alter the color with color-light and color-dark.
  • You can change the dot animation with slide and it's modifiers up, down, left and right.
various matrix examples
<div class="soon"
     data-due="2017"
     data-face="matrix color-light dot-round">
</div>

<div class="soon"
     data-due="2017"
     data-face="matrix color-dark spacey slide left">
</div>

<div class="soon"
     data-due="2017"
     data-face="matrix color-light shadow-soft">
</div>

<div class="soon"
     data-due="2017"
     data-face="matrix tight dot-square slide">
</div>

<div class="soon"
     data-due="2017"
     data-face="matrix 3x5 spacey dot-square">
</div>

Ring

The ring visual can be configured by adding the following parameters to the data-visual attribute.

  • color-light and color-dark for light and dark color variants.
  • Control progress shadow styles with progress-shadow-hard, progress-shadow-soft or progress-glow.
  • Control background shadow styles with background-shadow-hard, background-shadow-soft or background-glow.
  • width-thick and width-thin to render a different width ring. When using the visual biulder it is possible to fine tune both the progress and the background width independently.
  • Add cap-round to render rounded ring end points.
  • Add offset-{percentage} to define the starting point of the ring.
  • Add length-{percentage} to define the length of the ring.
  • Add gap-{percentageg} to define the size of the gaps between the progress bar and the background.
  • Add the flip value to flip the progress bar in the other direction and make it fill the ring instead of run empty.

Of course you can also fine tune all these values using CSS. See the presets page for some examples.

different ring visual styles
<div class="soon"
     data-due="2017"
     data-visual="ring cap-round">
</div>

<div class="soon"
     data-due="2017"
     data-visual="ring shadow-hard flip">
</div>

<div class="soon"
     data-due="2017"
     data-visual="ring color-dark length-50 gap-2,5">
</div>

<div class="soon"
     data-due="2017"
     data-visual="ring color-dark shadow-soft offset-25 cap-round">
</div>

<div class="soon"
     data-due="2017"
     data-visual="ring color-light width-thin glow">
</div>

<div class="soon"
     data-due="2017"
     data-visual="ring color-dark cap-round width-thick gap-5">
</div>

Fill

The fill visual can be configured with the following parameters.

  • color-light and color-dark for light and dark color variants.
  • Use corners-round and corners-sharp to control the box corner style.
  • Use to-top, to-top-right, to-right, to-bottom-right, to-bottom, to-bottom-left, to-left and to-top-left to control the direction of the background fill.

Of course you can also fine tune all these values using CSS. See the presets page for some examples.

different fill styles
<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill corners-sharp color-light to-top">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill to-top-right color-dark ">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill corners-sharp color-light to-right corners-round ">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill corners-sharp color-dark to-bottom">
</div>

<div class="soon"
     data-due="2017"
     data-face="slot"
     data-visual="fill color-light to-left">
</div>

Linking to other functionality

These options are often related to connections with other systems and you'll probably only need them if you're an experienced developer.

Placeholder

If you want to use text within the soon element you can decide where the counter should be created by adding the <span class="soon-placeholder"></span> element. Soon will replace that element with the counter. You can add your own HTML around it.

placeholder setup
<div class="soon" data-due="in 10 minutes" data-layout="line" data-format="m,s">

    Product launch in <span class="soon-placeholder">10 minutes</span>

</div>
Product launch in 10 minutes

Now

Sometimes you want to control the current date yourself instead of relying on the browser date. The data-now attribute allows you to set a server date. It accepts the same format as the data-due attribute.

Create

If you want to create a Soon element manually, you can call the Soon.create(element,options) method and pass a reference to the element as a paremeter the second parameter contains all the options. If you're using jQuery you can call $(selector).soon().create(options).

options
<script>
// available options
var options = {

    // data-since
    since:null,

    // data-due
    due:"2017",

    // data-now
    now:null,

    // data-layout
    layout:"group",

    // data-face
    face:"text",

    // data-visual
    visual:null,

    // data-format
    format:null,

    // data-singular
    singular:false,

    // data-reflect
    reflect:false,

    // data-scale-max
    scaleMax:"m",

    // data-scale-hide
    scaleHide:null,

    // data-separate-chars
    separateChars:true,

    // data-cascade
    cascade:true,

    // data-separator
    separator:"",

    // data-labels-*
    labelsYears:null,
    labelsDays:null,
    labelsHours:null,
    labelsMinutes:null,
    labelsSeconds:null,

    // data-padding
    padding:true,

    // data-padding-*
    paddingDays:null,
    paddingHours:null,
    paddingMinutes:null,
    paddingSeconds:null,

    // data-event-complete
    eventComplete:null,

    // data-event-tick
    eventTick:null
};
</script>

<!-- example -->
<div id="my-soon-to-be-counter"></div>
<script>

    // get the element
    var element = document.getElementById('my-soon-to-be-counter');

    // turn it into a Soon counter
    Soon.create(element,{
        'due':'in 10 seconds'
    });

</script>

Destroy

If you want to remove a Soon element, you can call the Soon.destroy(element) method and pass a reference to the element as a paremeter. If you're using jQuery you can also call $(selector).soon().destroy()

Freeze, Unfreeze

If you want to pause the timer you can use the freeze call. Soon.freeze(element), if you want to have the timer resume use the unfreeze call Soon.unfreeze(element). When pausing the time is just frozen, the countdown will recalculated the passed time on unfreeze and will jump the amount of seconds you paused the timer.

Redraw

If you want to redraw the Soon element, for instance after you've modified or resized the parent DOM element, you can call the Soon.redraw(element) method and pass a reference to the element as a paremeter. If you're using jQuery you can also call $(selector).soon().redraw(). Soon calls this method when automatically on page load and when the browser window is resized.

Option Override

You can use the setOption call to change a setting after you've created the counter. Soon.setOption(element,'due','2017') or $(element).soon().setOption('due','2017') will change the due date to 2017. Setting multiple properties at once can be done with the setOptions(optionsObject) call. For instance Soon.setOptions(element,{'due':'2017','padding':false}).

Complete Event

If you want to run JavaScript after the counter has run out you can bind your function to the onComplete callback using the data-event-complete attribute.

calling a function when done
<script>
    function happyNewYear() {
        alert('Cheers!');
    }
</script>
<div class="soon"
     data-due="2017"
     data-event-complete="happyNewYear">
 </div>

Tick Event

You can bind a JavaScript function to the counter tick event. Use the data-event-tick attribute or the matching option. See the example Complete Event for similar example code.

listening to the tick event
<script>
    function tick(milliseconds, due) {
        document.getElementById('soon-seconds').innerHTML = milliseconds;
    }
</script>

<div id="soon-seconds"></div>

<div class="soon"
     data-due="in 30 seconds"
     data-event-tick="tick">
</div>

Kickstart

If you want to prevent the automatic loading of Soon elements on the page add the data-auto="false" attribute to the soon script tag.

blocking autoload
<script src="soon.min.js" data-auto="false"></script>

FAQ

Show message when done

when the timer runs out, show a message and hide the timer.

show message
<div style="display:none;" id="soon-message">
    <p>Hello!</p>
</div>

<div class="soon"
     id="soon-counter"
     data-due="in 5 seconds"
     data-event-complete="showMessage">
</div>

<script>
    function showMessage() {
        document.getElementById('soon-message').style.display = '';
        document.getElementById('soon-counter').style.display = 'none';
    }
</script>

Change color when nearly done

When the timer has only 5 seconds left, change the color to red.

change color
<div class="soon"
     id="soon-counter"
     data-due="in 10 seconds"
     data-event-tick="testEnd">
</div>

<script>
    function testEnd(secondsLeft) {
        if (secondsLeft <= 5000) {
            document.getElementById('soon-counter').style.color = 'red';
        }
    }
</script>

Pause & resume the countdown

Pause and resume the countdown with a button. The timer will not continue where it was paused as the time till the due date has changed while being paused. For this reason the functions are named freeze and unfreeze.

pause and resume
<div class="soon"
     id="soon-counter"
     data-due="2017">
</div>

<button type="button" id="toggle-button">toggle</button>

<script>

    var frozen = false;
    var counter = document.getElementById('soon-counter');
    var button = document.getElementById('toggle-button');

    button.addEventListener('click',function(){
        if (frozen) {
            Soon.unfreeze(counter);
        }
        else {
            Soon.freeze(counter);
        }
        frozen = !frozen;
    });
</script>