Documentation

Learn how to use Sequence.js and create your own theme

Introduction

Sequence.js is a JavaScript library that provides a responsive CSS framework for creating unique sliders, presentations, banners, and other step-based applications.

This documentation can be treated as both a tutorial and reference. If this is your first time using Sequence.js, to get a good understanding of how it works, we recommend you read down to Options and copy the provided code examples into your own files. As you make your way through the documentation, you will build up a simple version of the Sequence.js Basic Theme to best demonstrate Sequence.js’ use.

If you’d rather just choose a theme that you can easily customize and add your own content to, visit the Sequence.js Theme Store for pre-built free and premium themes. Should you wish to modify the animations of a theme, head to Animation.

Let’s get started.

Download Sequence.js

Sequence.js can also be installed using the Bower command:

bower install sequencejs

or NPM:

npm install sequencejs

Package Contents

Some directories and files in the package that you may want to familiarize yourself with:

  • index.html: Demonstrates Sequence.js’ Basic Theme
  • scripts:
    • sequence.js: Production ready, unminified version of Sequence.js
    • sequence.min.js: Production ready, minified version of Sequence.js
  • src:
    • sequence.js: Development version of Sequence.js
  • Gruntfile.js: Provides a production environment. See Using Grunt.

Setting Up a Theme

Setting up a theme consists of:

  1. adding Sequence.js’ JavaScript and HTML structure to the page
  2. adding your content and styling it
  3. animating the canvas and/or content, and telling Sequence.js which elements to watch

Add Sequence.js

To add the Sequence.js library, place a link to Sequence.js, its third-party files, and the theme options file just before the “ element in your HTML page:

<script src="scripts/imagesloaded.pkgd.min.js"></script>
<script src="scripts/hammer.min.js"></script>
<script src="scripts/sequence.min.js"></script>
<script src="scripts/sequence-theme.basic.js"></script>

Note #1: imagesloaded.pkgd.min.js and hammer.min.js provide functionality for Sequence.js’ preloader and touch features. These files are optional and can be omitted should you choose not to use these features. You may like to disable these features via Sequence.js’ options but the absence of third-party files will disable them automatically.

Note #2: Where appropriate, you can instead place these scripts in the <head></head> of your page within a window.onload function or jQuery’s $(document).ready().

RequireJS Support: Sequence.js supports AMD and as such, it and its dependencies can be loaded via requireJS. See an example here.

Code specific to official Sequence.js themes will be placed in an options file with the naming convention sequence-theme.<theme -name>.js. Code inside an options file initiates Sequence.js, changes its default settings, and customizes Sequence.js where necessary via its API.

Initiate Sequence.js like so (in scripts/sequence-theme.basic.js for example):

  // Get the Sequence element
  var sequenceElement = document.getElementById("sequence");

  var options = {
    // Place your Sequence options here to override defaults
    // See: http://sequencejs.com/documentation/#options
    keyNavigation: true,
    fadeStepWhenSkipped: false
  }

  // Launch Sequence on the element, and with the options we specified above
  var mySequence = sequence(sequenceElement, options);

With this code, the HTML element that Sequence.js will be attached to <div id="sequence"></div> has been saved (HTML will be added in a moment), and Sequence.js has been initiated.

The instance of Sequence.js has been saved into a variable (var) called mySequence. The variable name is entirely of your choosing and, if necessary, will allow you to interact with Sequence.js via custom JavaScript which is explained in API.

The Sequence.js function sequence(), accepts an HTML element and options as its arguments. The HTML element is required, but if you don’t want to change Sequence.js’ default options, you can ignore the options argument altogether, like this var mySequence = sequence(sequenceElement).

The above code example turns on the keyNavigation feature to enable users to control navigation between steps via the keyboard’s left and right arrow keys. This is useful during development of a Sequence.js theme as you can quickly navigate between steps. More on customizing Sequence.js’ functionality using Options later.

It is possible to place multiple instances of Sequence.js on the same page, like so:

  var sequenceElement1 = document.getElementById("sequence1");
  var sequenceElement2 = document.getElementById("sequence2");

  var mySequence1 = sequence(sequenceElement1);
  var mySequence2 = sequence(sequenceElement2);

Here the page will have two instances of Sequence.js, one attached to <div id="sequence1"></div>, the other <div id="sequence2"></div>.

Add HTML (Structure)

Wherever you’d like Sequence.js to appear on a page, add Sequence.js’ HTML structure like so:

<div id="sequence">
  <ul class="seq-canvas">
    <li>
      Step 1 Content
    </li>
    <li>
      Step 2 Content
    </li>
    <li>
      Step 3 Content
    </li>
  </ul>
</div>

Sequence.js’ HTML structure consists of:

  • A container (any element with an unique ID of your choosing)
  • A canvas (any element with the class of seq-canvas)
  • Steps, which hold your content (think of these as slides — we just like the name steps better because they do a whole lot more than just slide!). You can have as many steps as you wish.

Container Element

The container is useful for the following:

  • Applying a width and height
  • Centering the Sequence.js element on the page
  • Applying overflow: hidden; so no content appears outside of the container’s boundaries
  • Adding additional Sequence.js elements such as navigation and pagination

Canvas Element

The canvas holds the steps.

By default, the animateCanvas option is enabled. This will make Sequence.js determine the offset positions of each step and move the canvas when a step is navigated to. More on this in Animating the Canvas.

With Sequence.js initiated and the HTML structure in place, when viewed in a browser Sequence.js will look like the following. Try pressing your browser’s left/right arrow keys to navigate between steps and see how Sequence.js automatically animates the canvas to always show the active step.

Basic canvas animation

Step Elements

The steps hold your content. When a step is navigated to, it is given the class seq-in, allowing you to animate a step’s content to its “in” position. Then, when a step is navigated away from, the step is given a seq-out class so you can move any of its elements to an “out” position, as you see fit. More on this in Animating Content.

When a step becomes active (one that is being viewed), it is given a higher z-index property than the others, so that the active step is positioned on top. This functionality can be changed via the moveActiveStepToTop option.

Choosing Elements for the Canvas and Steps

In the last code example, an unordered list <ul> is used for the canvas and <li> for the steps, but Sequence.js will allow you to use other elements too. For example, assuming you want to use <section> and <article>:

<div id="sequence">
  <section class="seq-canvas">
    <article>
      Step 1 Content
    </article>
    <article>
      Step 2 Content
    </article>
    <article>
      Step 3 Content
    </article>
  </section>
</div>

Sequence.js knows the canvas is whichever element you give the seq-canvas class and the steps are the canvas’ immediate descendants (children), in this case, the </article><article> elements.

Add a No-JavaScript Fallback

In a small percentage of browsers, JavaScript may be disabled which is the technology Sequence.js is built upon. In this case, to prevent an empty container from showing, nominate a step to be displayed by giving it a class of seq-in:

<div id="sequence">
  <ul class="seq-canvas">
    <li class="seq-in">
      Step 1 Content
    </li>
    <li>
      Step 2 Content
    </li>
    <li>
      Step 3 Content
    </li>
  </ul>
</div>

Here the first step is nominated to be displayed if JavaScript is disabled.

The seq-in and seq-out classes will be explained in Animating Content.

Add Content

To add content to a step, place HTML within each step element:

<div id="sequence">
  <ul class="seq-canvas">

    <li class="step1">
      <div class="content">
        <h2 data-seq>Powered by Sequence.js</h2>
        <h3 data-seq>The open-source CSS animation framework.</h3>
      </div>
    </li>

    <li class="step2">
      <div class="content">
        <h2 data-seq>Create Unique Animated Themes</h2>
        <h3 data-seq>For responsive sliders, presentations, <br />banners, and other step-based applications.</h3>
      </div>
    </li>

    <li class="step3">
      <div class="content">
        <h2 data-seq>No Restrictions, Endless Possibilities</h2>
        <h3 data-seq>Use the HTML and CSS syntax you're used to. <br />No JavaScript knowledge required.</h3>
      </div>
    </li>

  </ul>
</div>

Beyond the initial structure of containing element > canvas > steps, there are no limitations to what elements you can use in your Sequence.js content. Add as many elements as you like, a <video> element, a .gif, a plain old <div>, an <iframe>…it is entirely up to you.

Pay careful attention to the data-seq attributes added to some of the HTML elements. This is known as Sequence.js’ watch attribute. It tells Sequence.js this element will transition and Sequence.js should watch the element to determine when the step has finished animating. More on this later in Watch Elements.

Add Styles

As with the JavaScript options file, official Sequence.js themes use the naming convention sequence-theme.<theme -name>.css for its stylesheets.

Stylesheets should be added to the same page the Sequence.js HTML has been added to by placing a reference in between the <head></head> element of the page:

<link href="css/sequence-theme.basic.css" rel="stylesheet" media="all">

The following CSS rules add a layout and cosmetic styles to the example Sequence.js theme:

/* Style the Sequence container */
#sequence {
  position: relative;
  width: 100%;
  height: 585px;
  max-width: 100%;
  overflow: hidden;
  margin: 0 auto;
  padding: 0;
  font-family: sans-serif;
}

/* Reset */
#sequence .seq-canvas,
#sequence .seq-canvas > * {
  margin: 0;
  padding: 0;
  list-style: none;
}

/* Make the canvas the same dimensions as the container and prevent lines from
   wrapping so each step can sit side-by-side */
#sequence .seq-canvas {
  position: absolute;
  height: 100%;
  width: 100%;
  white-space: nowrap;
  font-size: 0;
}

/* Make the steps the same size as the container and sit side-by-side */
#sequence .seq-canvas > * {
  display: inline-block;
  vertical-align: top;
  width: 100%;
  height: 100%;
  white-space: normal;
  text-align: center;
  color: white;
}

/* Used to vertically center align the .content element */
#sequence .seq-canvas > li:before {
  content: "";
  display: inline-block;
  vertical-align: middle;
  height: 100%;
}

/* Vertically center align the .content element */
#sequence .content {
  display: inline-block;
  vertical-align: middle;
  margin: 0 4%;
  font-size: 16px;
}

#sequence .step1 {
  background-color: #279fe5;
}

#sequence .step2 {
  background-color: #f96852;
}

#sequence .step3 {
  background-color: #2bbf8e;
}

#sequence h2,
#sequence h3 {
  margin: 0;
  display: block;
  line-height: 120%;
}

#sequence h2 {
  margin-bottom: .5em;
  font-family: 'Roboto', sans-serif;
  font-size: 2.6em;
}

#sequence h3 {
  font-size: 1.4em;
}

A breakdown of what the above CSS does:

  • The Sequence.js container is made 100% wide and 585px tall, centered, and content is prevented from overflowing its boundaries
  • A mini-reset is applied to the canvas and its steps for better browser consistency
  • The canvas and steps are made the same width/height as the container
  • The steps are made to sit side-by-side (using display: inline-block and white-space: nowrap)
  • <div class="content"></div> is vertically aligned in the center
  • Each step is given a different background color
  • General styles are applied to the text

When viewed in the browser, the example theme now appears like so:

Basic theme styled

That’s cool, but not that impressive though, is it? Don’t worry, this is just the very start of what Sequence.js is capable of – your imagination is the only limitation!

The content is now styled nicely and Sequence.js is automatically animating the canvas to show each step as it becomes active. The real power of Sequence.js comes from its ability to animate content as well.

Tip: Sequence.js adds various class names to its container and other related elements to allow you to further style it in its various states. See Styling States for more information.

Animation

Both Sequence.js’ canvas and content can be animated.

Animating Content

Sequence.js steps have three phases that they go through when they become active and inactive again.

  • Start: The starting position prior to the step becoming active
  • In: The animate in position for when the step is active
  • Out: The animate out position for when the step is no longer active

When Sequence.js loads, its first step (by default) will be active, and as such, will be given the class seq-in. When the next step is navigated to, step 1 will be given the class seq-out moving it into the out phase. Step 2 will be moved to its start phase and then given the class of seq-in which will move it to its in phase. This process will repeat with each step and is reversed when navigating between steps backwards.

By applying styles to these class names, unique transitions can be applied to Sequence.js themes — no two themes ever need be the same!

Take the following CSS as an example:

/* Starting positions */
#sequence h2,
#sequence h3 {
  opacity: 0;
  -webkit-transition-duration: 0.4s;
  transition-duration: 0.4s;
}

#sequence h2 {
  -webkit-transform: translate(0, -20px);
  transform: translate(0, -20px);
}

#sequence h3 {
  -webkit-transform: translate(0, 20px);
  transform: translate(0, 20px);
}

/* Animate in positions for content */
#sequence .seq-in h2,
#sequence .seq-in h3 {
  opacity: 1;
  -webkit-transform: translate(0, 0);
  transform: translate(0, 0);
}

/* Animate out positions for content */
#sequence .seq-out h2,
#sequence .seq-out h3 {
  opacity: 1;
  -webkit-transform: translate(0, 0);
  transform: translate(0, 0);
}

Previewed in a browser, the above CSS make the example theme appear like so:

Basic theme animated

Using the seq-in and seq-out classes, the content is animated. Each time a step becomes active, the <h2> and <h3> elements fade in and subtly transition into place.

Let’s take a deeper look at how that worked.

Firstly, the start phase for the animated elements:

/* Starting positions */
#sequence h2,
#sequence h3 {
  opacity: 0;
  -webkit-transition-duration: 0.4s;
  transition-duration: 0.4s;
}

#sequence h2 {
  -webkit-transform: translate(0, -20px);
  transform: translate(0, -20px);
}

#sequence h3 {
  -webkit-transform: translate(0, 20px);
  transform: translate(0, 20px);
}

The elements are made transparent with the opacity property and are set up ready to transition over a period of .4s (4 seconds). <h2> was moved up by 20px and <h3> down by the same amount. These are the starting positions.

Next, the animate in phase:

/* Animate in positions for content */
#sequence .seq-in h2,
#sequence .seq-in h3 {
  opacity: 1;
  -webkit-transform: translate(0, 0);
  transform: translate(0, 0);
}

With these styles, when a step is given the seq-in class, its <h2> and <h3> will transition to opaque and move from their starting positions to these in positions.

Finally, the out phase:

/* Animate out positions for content */
#sequence .seq-out h2,
#sequence .seq-out h3 {
  opacity: 1;
  -webkit-transform: translate(0, 0);
  transform: translate(0, 0);
}

You may notice that these are the exact same styles applied for the animate in positions. That is because when the step goes from the in phase to out (losing its active status) and Sequence.js changes its class from seq-in to seq-out, we want the styles to remain in place. If animate out positions aren’t specified via the seq-out class, the elements will move back to their starting phase instead because the seq-in class is removed. You could also specify different styles for the seq-out class so that the elements do something different as they animate out. The choice is entirely up to you.

One of Sequence.js’ key philosophies is to allow you to use CSS in the way you are used to. As well as your favorite properties, media queries, etc, you can also make use of the cascade where necessary. The above styles relied on the cascade to apply the transition-duration of .4s to the <h2> and <h3> elements, regardless of whether the step they belong to has the seq-in or seq-out class. Utilising the cascade, you could specify a slower transition-duration for the out phase only, like so:

/* Animate out positions for content */
#sequence .seq-out h2,
#sequence .seq-out h3 {
  opacity: 1;
  -webkit-transform: translate(0, 0);
  transform: translate(0, 0);
  -webkit-transition-duration: 1s;
  transition-duration: 1s;
}

seq-in would still inherit the transition-duration of .4s but now seq-out has a transition-duration of 1s.

Watch Elements

You may have noticed the data-seq attributes on some of the elements in the example theme.

<div id="sequence">
  <ul class="seq-canvas">

    <li class="step1">
      <div class="content">
        <h2 data-seq>Powered by Sequence.js</h2>
        <h3 data-seq>The open-source CSS animation framework.</h3>
      </div>
    </li>

    <li class="step2">
      <div class="content">
        <h2 data-seq>Create Unique Animated Themes</h2>
        <h3 data-seq>For responsive sliders, presentations, <br />banners, and other step-based applications.</h3>
      </div>
    </li>

    <li class="step3">
      <div class="content">
        <h2 data-seq>No Restrictions, Endless Possibilities</h2>
        <h3 data-seq>Use the HTML and CSS syntax you're used to. <br />No JavaScript knowledge required.</h3>
      </div>
    </li>

  </ul>
</div>

This attribute is known as Sequence.js’ watch attribute. It tells Sequence.js that it should watch the element to determine when the step has finished animating.

Telling Sequence.js which elements it should watch is an important part in creating a Sequence.js theme. Many of Sequence.js’ features rely on this ability to watch element, such as autoPlay, pagination, the stepStarted/stepEnded callbacks available via the API, and more.

Take the autoPlay feature as an example. This enables Sequence.js to automatically navigate between steps after a given time has past. To do this, Sequence.js needs to know which elements you plan on animating so it can wait for them to end before considering the step having finished animating. When a step finishes, Sequence.js will then automatically navigate to the next step after the autoPlayInterval time has experience, as defined in the autoPlay options.

In the example HTML above, Sequence.js is told that the <h2> and <h3> elements should be watched via the data-seq attribute applied to them.

Assume it is specified in the CSS that both the <h2> and <h3> should move to their “in” position over half a second.

When the “in” phase begins, Sequence.js will look at all of its watched elements in the active step and determine how long they will transition for. In this case, they will transition for half a second. Sequence.js knows after a half second period the step has ended and it should begin the autoPlayInterval timer before automatically navigating to the next step.

If you don’t apply a transition to an element then it doesn’t need to be watched. However, you may like for an element to have a transition but not be watched. For example, you may want the <h2> and <h3> elements to transition over a half second period but apply a 10 second transition to an image that slowly moves in the background. In this instance, you might use the following HTML:

<div id="sequence">
  <ul class="seq-canvas">

    <li class="step1">
      <div class="content">
        <h2 data-seq>Powered by Sequence.js</h2>
        <h3 data-seq>The open-source CSS animation framework.</h3>
        <img src="fancy-product1.jpg" alt="Our first fancy product" />
      </div>
    </li>

    <li class="step2">
      <div class="content">
        <h2 data-seq>Create Unique Animated Themes</h2>
        <h3 data-seq>For responsive sliders, presentations, <br />banners, and other step-based applications.</h3>
        <img src="fancy-product2.jpg" alt="Our second fancy product" />
      </div>
    </li>

  </ul>
</div>

With the above code, Sequence.js knows you are happy to ignore the transition time for the <img /> element because you didn’t specify a data-seq attribute on it. The image will continue to transition over 10 seconds but autoPlay will cause the next step to be automatically navigated to after 5.5 seconds (.5 seconds for the <h2> and <h3> elements to animate plus 5 seconds as defined by the default autoPlayInterval option).

If you were to watch the <img /> element as well, the next step would be navigated to after 15 seconds (10 seconds for the <img/> element to finish animating (because it is the longest duration of all the watched elements), plus another 5 for the autoPlayInterval).

There are no restrictions on which content elements you watch. For example, you may wish to apply a transition to a parent and its child element but only watch the child, like so:

<li>
  <h2 data-seq>Create Unique Animated Themes</h2>
  <div class="product-details">
    <img data-seq src="fancy-product.jpg" alt="Our fancy product" />
  </div>
</li>

In the above code, Sequence.js will wait for the <h2> and <img /> elements to finish animating before it considers the step finished, but ignore any transitions applied to <div class="product-details">.

Another good example where watching elements can make a big difference is when navigationSkip is disabled. By default, navigationSkip is enabled so a user can move between steps before its elements have finished transitioning. Should your theme disable this option, the user will be forced to wait for a step to fully transition all of its watched elements prior to being able to navigate to another step. This poses somewhat of a user experience problem because preventing the navigation between steps may make your theme feel slow to the user. Careful consideration of which elements should be watched in a step may mean you can make the user wait a brief amount of time whilst the most important content elements in a step transition in, whilst other elements that may transition for longer, such as decorative ones, can still be skippable.

Animating the Canvas

By default, Sequence.js controls the animation of the canvas automatically via the animateCanvas option and the speed of animation via the animateCanvasDuration option.

When you position steps via CSS, Sequence.js will find the offsetLeft and offsetTop (the final X/Y positions of an element after top, margin, border etc CSS properties are applied) then uses these values to move the canvas so the current step is always shown within the container. Providing the properties you used to layout your steps effect the offset position of the step, Sequence.js will animate to an active step as necessary.

Note: Using CSS transforms does not effect the offset value of an element and as such, we recommend you avoid the use of transforms to lay out step elements and instead rely on position, and top, right, bottom, left. However, Sequence.js will always use transforms to animate its canvas for best performance via hardware acceleration.

Tip: Should you wish to modify how the canvas animates or apply additional styles, the container is given class names that represent the active step, prefixed with seq-. For example, when step1 is active, the container will have the class of seq-step1, and so on.

Example Canvas/Step Layouts

Unless you decide to disable the animateCanvas feature, Sequence.js will automatically animate the canvas to always show the active step. this means you can position your steps relative or absolute — in a grid, in a random order, and so on — and Sequence.js will move its canvas accordingly so the top left of the active step appears at the top left of the container.

The following are some of the layout types you might like to try for yourself.

Traditional Slider (Side-by-Side) Layout

The following image shows a traditional side-by-side layout, typically used for applications such as presentation sliders:

Side-by-side layout

This layout can be achieved using the following styles:

/* Style the Sequence container */
#sequence {
  position: relative;
  width: 100%;
  height: 585px;
  max-width: 100%;
  overflow: hidden;
  margin: 0 auto;
  padding: 0;
}

/* Make the canvas the same dimensions as the container and prevent lines from
   wrapping so each step can sit side-by-side */
#sequence .seq-canvas {
  position: absolute;
  height: 100%;
  width: 100%;
  white-space: nowrap;
  font-size: 0;
}

/* Make the steps the same size as the container and sit side-by-side */
#sequence .seq-canvas > * {
  display: inline-block;
  vertical-align: top;
  width: 100%;
  height: 100%;
  white-space: normal;
  font-size: 16px;
}

With this code, the container is made to hide any overflowing content (in the image, content is overflowing the container to demonstrate movement of the canvas but with overflow: hidden applied, nothing would appear outside of the container). The canvas is made the same width/height as the container and white-space: nowrap on the canvas, along with display: inline-block on the steps (via the #sequence .seq-canvas > * selector) will make the steps sit side-by-side. white-space: normal is then applied on the steps so they don’t inherit white-space: nowrap from the canvas and effect the content of the steps in an undesirable way.

With the animateCanvas feature enabled, Sequence.js will automatically move the canvas when each step becomes active to position the top/left of that step with the top/left of the container. In the image, step 2 is shown as the active step.

##### Traditional Slider (Top-to-Bottom) Layout

The following image shows a traditional top-to-bottom layout, typically used for applications such as presentation sliders:

Top-to-bottom layout

This layout uses exactly the same styles as the side-by-side layout, with the only difference being white-space: nowrap and white-space: normal are not used.

In the example image, step 2 is shown as the active step and the canvas will move up/down when the steps are navigated between.

No Layout (When Canvas Animation Isn’t Required)

You may be thinking this is all good but I don’t want the canvas to animate, just the content. No problem! The following image shows an example of a Sequence.js theme where by all of the steps are in the same position:

No layout

Note that the steps are slightly offset in the image although this is just to show the steps are on top of one another and really all have the same position. Step 2 is the active step. Sequence.js controls the stacking order of the steps via its moveActiveStepsToTop option which is enabled by default. When a step is active, Sequence.js will give it the highest z-index value so it appears on top of the other steps.

The following CSS can be used to stack steps on top of one another:

/* Style the Sequence container */
#sequence {
  position: relative;
  width: 100%;
  height: 585px;
  max-width: 100%;
  overflow: hidden;
  margin: 0 auto;
  padding: 0;
}

/* Make the canvas and steps the same dimensions as the container  */
#sequence .seq-canvas,
#sequence .seq-canvas > * {
  position: absolute;
  height: 100%;
  width: 100%;
}

As with the other layouts, the container is given width/height properties and content is prevented from appearing outside of it. The canvas and its steps are than made the same size as the container.

You might use this layout (or lack of) when you just want the content to animate in and out as each step becomes active.

Browser Support and Fallback Mode

Sequence.js aims to work fully in the latest versions of all major browsers that support CSS transitions and transforms, as well as older browsers that don’t (Internet Explorer 8 & 9) via a fallback mode.

Please see the list of supported browsers.

In fallback mode, content animation is disabled. Sequence.js gives all steps a class of seq-in and will make each step position: absolute. When the user navigates between steps, the step’s left position will be animated, the current step to -100% or 100% (depending on the direction of navigation) and the next to 0 — much like a traditional slider. This way, the user still gets to see all of the content available in your Sequence.js theme, just without so many fancy effects. In fallback mode, animation is controlled via JavaScript.

When in fallback mode, the Sequence.js container is given a class of seq-fallback to allow you to change styles for a fallback theme accordingly and HTML structure is given the following styles via JavaScript:

<div id="sequence">
  <ul class="seq-canvas" style="width: 100%; height: 100%;">
    <li style="position: absolute; width: 100%; height: 100%;">
      Step 1 Content
    </li>
  </ul>
</div>

Speed of animation in Fallback Mode is controlled via the speed option.

Please see browser support for each individual property on caniuse.com:

Options

Sequence.js comes with many options that allow you to easily control its features and how it behaves.

As explained in Add Sequence.js, each instance of Sequence.js can be passed options that override Sequence.js’ defaults. Options are stored in an object passed to the sequence() function, like so:


// Get the Sequence element var sequenceElement = document.getElementById("sequence"); // Change Sequence's default options var options = { autoPlayInterval: 500 }; // Initiate Sequence var sequence1 = sequence(sequenceElement, options);

Multiple instances of Sequence.js can be passed the same options:


// Get the Sequence elements var sequenceElement1 = document.getElementById("sequence1"); var sequenceElement2 = document.getElementById("sequence2"); // Change Sequence's default options var options = { autoPlayInterval: 500 }; // Initiate Sequence var sequence1 = sequence(sequenceElement1, options); var sequence2 = sequence(sequenceElement2, options);

Or differing options:


// Get the Sequence elements var sequenceElement1 = document.getElementById("sequence1"); var sequenceElement2 = document.getElementById("sequence2"); // Change Sequence's default options var options1 = { autoPlayInterval: 500 }; var options2 = { autoPlayInterval: 1000 } // Initiate Sequence var sequence1 = sequence(sequenceElement1, options1); var sequence2 = sequence(sequenceElement2, options2);

The following is the complete set of options implemented within Sequence.js:

General

startingStepId

  • Type: Number
  • Default: 1

The step that should first be displayed when Sequence.js loads.

startingStepAnimatesIn

  • Type: true/false
  • Default: false

Whether the starting step should animate from its start phase to its in phase.

  • true: The starting step will begin in its start phase and move to its in phase when Sequence.js loads.
  • false: The starting step will begin in its in phase when Sequence.js loads.

Note: In fallback mode, startingStepAnimatesIn will always be false.

cycle

  • Type: true/false,
  • Default: true

Whether Sequence.js should navigate to the first step after the last step and vice versa.

  • true: When a user or Sequence.js’ autoPlay navigates forward from the last step, Sequence.js will go to the first step. Likewise, when a user/autoPlay navigates backwards from the first step, Sequence.js will go to the last step.
  • false: When a user/autoPlay navigates forward from the last step or backwards from the first step, Sequence.js will not go to another step.

phaseThreshold

  • Type: true/false or a number representing milliseconds
  • Default: true

Whether there should be a delay between the current step animating out and the next step animating in.

  • true: the next step will not animate in until the current step has completely animated out.
  • false: the next step will animate in at the same time as the current step animating out.
  • A number: The amount of milliseconds to wait after animating the current step out, before the next step is animated in.

reverseWhenNavigatingBackwards

  • Type: true/false
  • Default: false

Whether animations should be reversed when a user navigates backwards by clicking a previous button/swiping/pressing the left key.

  • true: when navigating backwards, Sequence.js will animate the preceding step from its animate-out position to its animate-in position (creating a reversed animation).
  • false: when navigating backwards, Sequence.js will animate the preceding step from its starting position to its animate in position (as it does when navigating forwards).

reverseTimingFunctionWhenNavigatingBackwards

  • Type: true/false
  • Default: false
  • Dependencies: reverseWhenNavigatingBackwards: true
  • Added: 2.1.0

Whether the transition-timing-function should be reversed when a user navigates backwards by clicking a previous button/swiping/pressing the left key.

  • true: when navigating backwards, Sequence.js will automatically reverse a transition-timing-function property so the value ease-in will become ease-out and so on.
  • false: when navigating backwards, Sequence.js will not automatically reverse a transition-timing-function.

moveActiveStepToTop

  • Type: true/false
  • Default: true

Whether a step should be positioned higher in the stacking order than other steps whilst it is active, to bring it above the others.

  • true: an active step will be given a a stacking order value the same as the number of steps in the Sequence.js instance (bringing it to the top) and the previous step will be given a value one less than the number of steps in the Sequence.js instance.
  • false: steps will not have a stacking order applied to them. The cascade will take effect whereby elements positioned lower in the document will be stacked on top of those it succeeds, unless otherwise modified via custom CSS.

Canvas Animation

Canvas animation causes Sequence.js to automatically animate the canvas element to show the next step. Automatic animation consists of finding the next step’s position and then directly animating to it.

If you’d like to customize how the canvas animates, set animateCanvas to false. Regardless of the animateCanvas option, the Sequence.js element is given a class representing the current step being viewed. seq-step1, seq-step2, and so on. These classes allow you to control canvas animation manually.

Browser Support: In modern browsers, animation is powered by CSS transitions and JavaScript in non-supporting browsers.

animateCanvas

  • Type: true/false
  • Default: true

Whether Sequence.js should automatically control the canvas animation when a step is navigated to.

  • true: Sequence.js will control the canvas animation when a step is navigated to.
  • false: Sequence.js will not control the canvas animation when a step is navigated to.

There are two reasons you may want to disabled animateCanvas:

  1. You don’t need the canvas to animate because its steps are layered on top of each other using position: absolute;.
  2. You want to manually control the canvas animation. When step 1 is viewed, the Sequence.js element will be given the class of seq-step1, and so on. Using these classes you can control animation manually using either CSS3 or JavaScript via Sequence.js’ API.

animateCanvasDuration

  • Type: A number representing milliseconds
  • Default: 250
  • Dependencies: animateCanvas: true

The amount of time it should take the canvas to automatically animate to the next step.

Autoplay

AutoPlay causes Sequence.js to automatically navigate to the next step every X amount of milliseconds after the transitions of watched elements in the active step have finished. AutoPlay by default is stopped when the user hovers over the Sequence.js element and can also be stopped/started via the autoPlay button and the methods available via the API.

autoPlay

  • Type: true/false
  • Default: false

Once the current step’s watched elements have finished animating (and the step is considered as finished), cause Sequence.js to automatically navigate to the next step after a period of time, as defined in autoPlayInterval.

  • true: Sequence.js will automatically navigate from step to step with an interval between each step (specified using the autoPlayInterval option).
  • false: Sequence.js will display the starting step until a user chooses to navigate using next/previous buttons, swiping, etc.

autoPlayInterval

  • Type: a number representing milliseconds
  • Default: 5000
  • Dependencies: autoPlay: true

The duration in milliseconds to wait before autoPlay navigates to the next step. Default is 5000 milliseconds or 5 seconds.

autoPlayDelay

  • Type: a number representing milliseconds
  • Default: null (the same value as autoPlayInterval)
  • Dependencies: autoPlay: true

The duration in milliseconds to wait before autoPlay navigates to the next step when started from an autoPlayButton, or sequence.start(delay) when the delay argument is true.

If you want Sequence.js to immediately navigate to the next step when started, set this to 0. This may be a good idea when your Sequence.js theme has no visual representation of having been stopped because the next step will immediately be navigated to and the user will see their interaction with the page had an immediate effect.

autoPlayDirection

  • Type: a number (1 = forward, -1 = reverse)
  • Default:1
  • Dependencies: autoPlay: true

The direction in which Sequence.js’ autoPlay should navigate.

  • 1: Sequence.js will navigate forwards, from step to step
  • -1: Sequence.js will navigate backwards, from step to step
autoPlayButton

See autoPlayButton in the User Interface section.

autoPlayPauseOnHover
  • Type: true/false
  • Default: true
  • Dependencies: autoPlay: true

Whether autoPlay should pause when the user hovers over Sequence.js. autoPlay will continue again when the user moves their cursor outside of Sequence.js.

Note: The user is only deemed to be hovering over Sequence.js when their cursor is within the container’s boundaries.

Navigation Skipping

Navigation skipping controls whether a step can be navigated to whilst another is actively animating and how to most gracefully deal with skipped steps when enabled.

Tip: A step is only considered as “active” whilst its watched elements are animating. Elements that are animating but not watched are ignored.

Browser Support: When in fallback mode (used by browsers that don’t have support for CSS transforms and transitions), navigation skipping is not allowed, regardless of the following options.

navigationSkip

  • Type: true/false
  • Default: true

Whether the user can navigate to a step before another step has finished animating.

  • true: The user can navigate to another step whilst the current one still has watched elements that are actively animating
  • false: The user is prevented from navigating to another step whilst the current one has watched elements that are actively animating

navigationSkipThreshold

  • Type: a number representing time in milliseconds
  • Default: 250
  • Dependencies: navigationSkip: true

Amount of time that must pass before another step can be skipped. Example, if the user hits the next button, a period of 250ms (by default) must pass before they can navigate to another step.

fadeStepWhenSkipped

  • Type: true/false
  • Default: true
  • Dependencies: navigationSkip: true

If a step is skipped before it finishes animating, cause it to fade out over a specific period of time (see fadeStepTime).

fadeStepTime

  • Type: a number representing time in milliseconds
  • Default: 500
  • Dependencies: navigationSkip: true, fadeStepWhenSkipped: true

How quickly a step should fade out when skipped (in milliseconds).

Browser Support: In modern browsers, animation is powered by CSS transitions and JavaScript in non-supporting browsers.

ignorePhaseThresholdWhenSkipped

  • Type: true/false
  • Default: false
  • Dependencies: navigationSkip: true

With ignorePhaseThresholdWhenSkipped set to true and a step is navigated away from whilst it is still animating, Sequence.js will treat the phaseThreshold option as being false, regardless of developer defined options. This may help improve user experience as when the user is quickly navigating between steps there won’t be any delay before the next step animates in — the user’s interaction is always presented with immediate action on screen.

preventReverseSkipping

  • Type: true/false
  • Default: false
  • Dependencies: navigationSkip: true

Whether the user can change the direction of navigation during steps animating (if navigating forward, the user can only skip forwards when other steps are animating but not backwards, and vice versa).

User Interface

Sequence.js has many options that allow you to customize the elements that allow the user to interact with Sequence.js.

The element types that can be added include:

Multiples of the same user interface type can be used in each instance of Sequence.js (except for preloader which currently only allows one per instance), if you wish to have a next button in each step for example.

When using multiple instances of Sequence.js, note that user interface elements by default will control all Sequence.js instances. A next button for example will control every instance of Sequence.js on the page. Should you wish to have an UI element only control one instance of Sequence.js, please use a rel attribute on the UI element, with a value the same as the id for the Sequence.js instance you want the UI element to control. For example:

<div rel="sequence1" class="seq-next">Next →</div>

<div id="sequence1">
  <!-- additional code removed for brevity -->
</div>

<div id="sequence2">
  <!-- additional code removed for brevity -->
</div>

In the above code example, we have two instances of Sequence.js on the page. With an attribute of rel="sequence1" applied to a next button, only <div id="sequence1"> will go to its next slide when the next button is clicked. Likewise, should we change the attribute to rel="sequence2", the second Sequence.js instance <div id="sequence2"> will navigate to its next slide. If the rel attribute is removed entirely, both instances will go to the next slide. This applies to all UI elements regardless of their position on the page — they can be within or outside of Sequence.js elements.

Next and Previous Buttons

Next and previous buttons allow the user to navigate between steps.

By default, these buttons are enabled, however, Sequence.js doesn’t automatically add these elements so the necessary HTML must be added to the page. For example, a next button can be added using the default class seq-next, like so:

<button type="button" class="seq-next">Next →</button>

Any element can be used as a next/previous button, as long as it is given the specified selector and is clickable.

nextButton
  • Type: true/false or a class/ID selector
  • Default: true

Defines a button that when clicked, causes the next step to become active.

<button type="button" class="seq-next">Next</button>
  • true: Use a next button with the default CSS selector (.seq-next)
  • false: Don’t use a next button
  • class/ID selector: Use a next button but change the default selector to a class/ID selector of you liking

Note: the button must be added to the HTML manually.

prevButton
  • Type: true/false or a class/ID selector
  • Default: true

Defines a button that when clicked, causes the previous step to become active.

<button type="button" class="seq-prev">Previous</button>
  • true: Use a previous button with the default CSS selector (.seq-prev)
  • false: Don’t use a previous button
  • class/ID selector: Use a previous button but change the default selector to a class/ID selector of you liking

Note: the button must be added to the HTML manually.

AutoPlay Button

An autoPlay button allows a user to stop and start autoPlay as they wish.

By default, the autoPlayButton is enabled, however, Sequence.js doesn’t automatically add the element so the necessary HTML must be added to the page. For example, an autoPlay button can be added using the default class seq-autoplay, like so:

<button type="button" class="seq-autoplay">Play</button>

Any element can be used as an autoPlay button, as long as it is given the specified selector and is clickable.

autoPlayButton
  • Type: true/false or a class/ID selector
  • Default: true
  • Dependencies: autoPlay: true

Defines a button that when clicked, toggles (starts/stops) the autoPlay feature.

  • true: Use an autoPlay button with the default CSS selector (.seq-autoplay)
  • false: Don’t use an autoPlay button
  • class/ID selector: Use an autoPlay button but change the default selector to a class/ID selector of you liking

Pagination Links

Pagination allows for a list of links that represents each step within Sequence.js. These links can be clicked to navigate to the relevant step.

pagination
  • Type: true/false or a class/ID selector
  • Default: true

Pagination associates immediate descendant elements within the pagination selector (.seq-pagination by default) to each Sequence.js step. If pagination is true, the following HTML can be included in your document to act as pagination:

<ul class="seq-pagination">
  <li>Step 1</li>
  <li>Step 2</li>
  <li>Step 3</li>
</ul>

When the first <li> element is clicked, Sequence will navigate to its first step. When the second is clicked, Sequence.js will navigate to its second step, and so on.

The pagination and its immediate descendants can consist of any element(s). So, if you’d prefer, you could use <div> and <button> elements instead of <ul> and <li> elements, like so:

<div class="seq-pagination">
  <button>Step 1</button>
  <button>Step 2</button>
  <button>Step 3</button>
</div>

The immediate descendants can also have child elements of their own. These additional elements do not affect how the pagination works.

When a Sequence.js step is navigated to (via any navigation method, such as clicking pagination links, pressing a keyboard key etc), the associated pagination link will be given a class of seq-current, so you can style the current pagination link as you wish:

HTML:

<ul class="seq-pagination">
  <li>Step 1</li>
  <li class="seq-current">Step 2</li>
  <li>Step 3</li>
</ul>

CSS:

.seq-pagination .seq-current {
  font-weight: bold;
}
  • true: Use pagination with the default CSS selector (.seq-pagination)
  • false: Don’t use pagination
  • class/ID selector: Use pagination but change the default selector to a class/ID selector of you liking

Note: the pagination elements must be added to the HTML manually.

Preloader

Sequence.js’ preloader allows the ability to hide content or display some form of loading indicator until your chosen content has loaded.

Sequence.js relies on the third-party imagesLoaded to determine when images have loaded. Third-party support details.

To use Sequence.js’ preloader, please add a reference to imagesloaded.pkgd.min.js above your reference to the Sequence.js library, like so:

<script src="scripts/imagesloaded.pkgd.min.js"></script>
<script src="scripts/sequence.min.js"></script>
preloader
  • Type: true/false or a class/ID selector
  • Default: false
  • true: Append the default preloader element with the CSS selector (.seq-preloader) to the Sequence.js element, and add the preloader styles to <head></head>

  • false: Don’t use a preloader
  • class/ID selector: Use a preloader element and styles of your own

When the preloader is being used, the Sequence.js element is give a class of seq-preloading. Both the Sequence.js element and the preloader element are given a class of seq-preloaded when preloading is complete.

When using the default preloader (preloader: true), default styles are also applied. These styles can be overridden via CSS (except for the animation wich is driven by SVG). If you’d like to use a preloader of your own, it’s recommend you use a CSS selector for the preloader element and apply your own preloader element to the page for styling however you please. To do this specify a custom preloader with your own class or ID selector on the preloader option, such as preloader: ".my-preloader" and add the element to your HTML, like so: <div class="my-preloader">Preloading...</div>. This element will have no default styles so you can style it using your own CSS. Like the default preloader, when Sequence.js finishes preloading, your custom preload element will be given the class seq-preloaded. You might like to use this class to apply styles to remove the preloader, such as display: none, z-index: -1 etc. A custom preloader element can be placed anywhere on the page.

If using the default preloader with the option preloader: true, the following HTML will be appended to the Sequence.js element:

HTML:

<div class="seq-preloader">
  <svg width="39" height="16" viewBox="0 0 39 16" xmlns="http://www.w3.org/2000/svg" class="seq-preload-indicator"><title>Sequence.js Preloading Indicator</title><desc>Three orange dots increasing in size from left to right</desc><g fill="#F96D38"><path class="seq-preload-circle seq-preload-circle-1" d="M3.999 12.012c2.209 0 3.999-1.791 3.999-3.999s-1.79-3.999-3.999-3.999-3.999 1.791-3.999 3.999 1.79 3.999 3.999 3.999z"/><path class="seq-preload-circle seq-preload-circle-2" d="M15.996 13.468c3.018 0 5.465-2.447 5.465-5.466 0-3.018-2.447-5.465-5.465-5.465-3.019 0-5.466 2.447-5.466 5.465 0 3.019 2.447 5.466 5.466 5.466z"/><path class="seq-preload-circle seq-preload-circle-3" d="M31.322 15.334c4.049 0 7.332-3.282 7.332-7.332 0-4.049-3.282-7.332-7.332-7.332s-7.332 3.283-7.332 7.332c0 4.05 3.283 7.332 7.332 7.332z"/></g></svg>
</div>

With the following CSS appended to <head></head> within <style></style> tags:

CSS:

  @keyframes seq-preloader {
    50% {
      opacity: 1;
    }

    100% {
      opacity: 0;
    }
  }

  .seq-preloader {
    background: white;
    visibility: visible;
    opacity: 1;
    position: absolute;
    z-index: 9999;
    height: 100%;
    width: 100%;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
  }

  .seq-preloader.seq-preloaded {
    opacity: 0;
    visibility: hidden;
    transition: visibility 0s .5s, opacity .5s;
  }

  .seq-preload-indicator {
    overflow: visible;
    position: relative;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }

  .seq-preload-circle {
    display: inline-block;
    height: 12px;
    width: 12px;
    fill: #F96D38;
    opacity: 0;
    animation: seq-preloader 1.25s infinite;
  }

  .seq-preload-circle-2 {
    animation-delay: .15s;
  }

  .seq-preload-circle-3 {
    animation-delay: .3s;
  }

  .seq-preload-indicator-fallback {
    width: 42px;
    margin-left: -21px;
    overflow: visible;
  }

  .seq-preload-indicator-fallback .seq-preload-circle {
    width: 8px;
    height:8px;
    background-color: #F96D38;
    border-radius: 100%;
    opacity: 1;
    display: inline-block;
    vertical-align: middle;
  }

  .seq-preload-indicator-fallback .seq-preload-circle-2 {
    margin-left: 3px;
    margin-right: 3px;
    width: 12px;
    height: 12px;
  }

  .seq-preload-indicator-fallback .seq-preload-circle-3 {
    width: 16px;
    height: 16px;
  }

Note: Vendor prefixes are omitted from the above CSS for brevity.

Changing Default Styles

If you’d like to use the default preloader but want to modify some of its styles, they can be easily overriden in your CSS. As the default styles are appended to the end of the <head></head> element (and your stylesheets will most likely be declared before it, you’ll need to be sure your overriding styles have a greater specifity. To do that, you can either make an overriding selector more specific or use the !important tag.

The following are some of the common changes made to the default preloader styles.

Color of Circle Indicators

To change the color of the preloader indicator circles, add the following to your stylesheet:

  .seq-preload-circle {
    fill: red !important;
  }

Background Color of Preloader

To change the background color of the preloader, add the following to your stylesheet:

  .seq-preloader {
    background: blue !important;
  }

Length of Fade Out

To change the speed at which the preloader fades out when preloading is complete, add the following to your stylesheet:

  .seq-preloader.seq-preloaded {
    transition: visibility 0s 3s, opacity 3s !important;
  }

This will fade the preloader out over 3 seconds. Note that two properties transition when preloading is complete; visibility and opacity. visibility is given a transition-duration of 0s and a transition-delay of 3s, with opacity given a transition-duration of 3s and no delay. This means that the opacity will fade out over 3 seconds. After those 3 seconds, the preloader’s visibility will instantly be changed to hidden.

preloadTheseSteps
  • Type: An integer array containing a list of step numbers
  • Default: [1]
  • Dependencies: preloader: true

Specify which steps should have their images loaded before Sequence.js initiates. By default, images in the first step are loaded before Sequence.js initiates.

The following example will load all images in steps 1 and 2:

preloadTheseSteps: [1, 2]
preloadTheseImages
  • Type: A string array containing a list of image sources
  • Default: []
  • Dependencies: preloader: true

Specify which images should be loaded before Sequence.js initiates. By default, no individual images are loaded (note that all images in step 1 load by default, as described in the preloadTheseSteps option).

The following example will load all images in step 1 (via the preloadTheseSteps option), as well as an image from step 2, an image in the footer of the page, and an image applied via CSS:

preloadTheseSteps: [1],
preloadTheseImages: [
  "images/step2image.png",
  "images/footer-logo.png",
  "css/images/background.png"
]
hideStepsUntilPreloaded
  • Type: true/false
  • Default: false
  • Dependencies: preloader: true

Specify whether steps should be hidden during preloading and then shown afterwards.

  • true: Hide steps until preloaded
  • false: Don’t hide steps during preloading
pausePreloader
  • Type: true/false
  • Default: false
  • Dependencies: preloader: true

Specify whether Sequence.js should pause its preloader, preventing it from being hidden even when preloading has finished. This is a debug only option and can be useful to test a preloader’s styles during development of a Sequence.js theme.

  • true: Prevent the preloader from hiding so it is always visible
  • false: The preloader should act as expected — hiding when preloading has finished

Styling States

Sequence.js will automatically add the following class names to the container and other Sequence.js related elements when required. All class names are prefixed with seq-. These class names can be used to further style your Sequence.js theme:

.seq-in

Added to a step when it becomes active. See Animating Content.

.seq-out

Added to a step when it becomes inactive. See Animating Content.

.seq-active

Added to $container when Sequence.js has been successfully initiated.

.seq-preloading

Added to $container and $preloader when Sequence.js begins preloading and removed when completed.

.seq-preloaded

Added to $container and $preloader when Sequence.js has finished preloading.

.seq-reversed

Added to $container when reverseWhenNavigatingBackwards is enabled and the user is navigating backwards. Useful for overriding animations that Sequence.js automatically reverses.

.seq-step1, .seq-step2, etc

Added to $container to represent the active step.

.seq-autoplaying

Added to $container and $autoPlay element when the autoPlay feature is active. Removed when inactive.

.seq-fallback

Added to $container when Sequence.js goes into fallback mode.

.seq-current

Added to the $pagination.currentLinks link when its related step is active.

.seq-touch

Added to $container when the browser supports touch capabilities

.seq-no-touch

Added to $container when the browser doesn’t support touch capabilities

Keyboard

Keyboard options enable the user to navigate to steps using specific keyboard buttons.

keyNavigation

  • Type: true/false
  • Default: false

Whether to allow the user to navigate between steps using the left/right arrow keys.

numericKeysGoToSteps

  • Type: true/false
  • Default: false

Whether Sequence.js should go to a specific step when the user presses a numeric key. Pressing 1 goes to step 1, 2 to step 2, and so on.

keyEvents

  • Type: An object or false

The public Sequence.js method that should occur when the left or right arrow keys are pressed.

By default the keyEvents option is the following object:

keyEvents: {
  left: function(sequence) {sequence.prev()},
  right: function(sequence) {sequence.next()}
}

When the left button is pressed, the Sequence.js event self.prev() is initiated. self.next() is initiated when the right button is pressed.

  • object: An object containing left and right properties that have a related public method to be executed when the left and right buttons are pressed
  • false: No keyboard events

Touch Swipe

Touch swipe capabilities are powered via the third-party library Hammer.js. Third-party support details.

Browser Support: Touch capabilities are disabled in Internet Explorer 8.

To use Sequence.js’ touch features, please add a reference to hammer.min.js above your reference to the Sequence.js library, like so:

<script src="scripts/hammer.min.js"></script>
<script src="scripts/sequence.min.js"></script>

swipeNavigation

  • Type: true/false
  • Default: true

Whether to allow the user to navigate between steps by swiping left and right on touch enabled devices.

swipeEvents

  • Type: An object or false
  • Default: {left: function(sequence) {sequence.next();}, right: function(sequence) {sequence.prev();}, up: undefined, down: undefined}

The public Sequence.js method that should occur when the user swipes in a particular direction.

By default the swipeEvents option is the following object:

swipeEvents: {
  left: function(sequence) {sequence.next();},
  right: function(sequence) {sequence.prev();},
  up: undefined,
  down: undefined
}

When the user swipes left, the Sequence.js event self.next() is initiated. self.prev() is initiated when the user swipes right.

By default, up and down swipe events aren’t specified as typically up/down swiping is reserved for scrolling. Should you specify up and/or down events, scrolling will be prevented on the Sequence.js element so care should be taken to ensure this doesn’t cause a user experience problem.

Note: Sequence.js will determine the best Hammer directions to use based on the events specified but should you wish, these directions as well as other Hammer options can be overriden by the publicly available sequence.hammerTime property.

  • object: An object containing left, right, up, and down properties that have a related public method to executed when the user swipes in one of those directions
  • false: No swipe events

swipeHammerOptions

  • Type: An object
  • Default: {}

Options to be used in the third-party Hammer.js library that powers touch functionality. See the Hammer.js Swipe Options for a complete list of options.

Sequence.js relies on Hammer’s default Swipe recognizer options.

The Hammer event used by Sequence.js is swipe.

Hash Tags

When enabled, the hash tag options will append a hash tag to a page’s URL, reflecting the currently active slide’s id or data-seq-hashtag attribute.

Note: The hashTags options make use of a “hash bang”, a hash followed by an exclamation point #!. This is to prevent the browser from jumping when the URL is changed.

Browser Support: In supporting browsers, pushState is used to change the URL.

hashTags

  • Type: true/false
  • Default: false
  • true: When a step is navigated to and becomes active, the hash tag will change to reflect the steps id attribute

  • false: the hash tag will not change
  • In the following example, when hashTags is enabled and the second step becomes active, the URL will be changed to end with the hash tag #!second-step. The name “second-step” is taken from the step’s id attribute.

    <div id="sequence">
      <ul class="seq-canvas">
        <li id="intro">
          <h2 data-seq>Built using Sequence.js</h2>
        </li>
        <li id="second-step">
          <h2 data-seq>Super awesome!</h2>
        </li>
      </ul>
    </div>
    

    hashDataAttribute

    • Type: true/false
    • Default: false
    • Dependencies: hashTags: true
  • true: the hash tag name, will not be taken from the step’s id attribute but instead a data attribute called data-seq-hashtag.

  • false: Use the id attribute instead of the data attribute.
  • In the following example, when hashTags and hashDataAttribute are true, and the first step becomes active, the URL will be changed to end with the hash tag #!superAwesome.

    <div id="sequence">
      <ul class="seq-canvas">
        <li id="intro" data-seq-hashtag="superAwesome">
          <h2 data-seq>Built using Sequence.js</h2>
        </li>
      </ul>
    </div>
    

    hashChangesOnFirstStep

    • Type: true/false
    • Default: false
    • Dependencies: hashTags: true

    Whether the hash tag should be changed when the first step becomes active.

    • true: The hash tag will change as soon as Sequence.js is initiated
    • false: The hash tag will not change when the first step becomes active but will change for every other step after that

    Fallback Mode

    The fallback mode is used when a browser does not fully support the features used by Sequence.js. For a more detailed description, please see Browser Support.

    Fallback mode options are included in the options of each instance of Sequence.js, like so:

      var options = {
        fallback: {
          speed: 500
        }
      };
    
      var sequenceElement = document.getElementById("sequence");
    
      var sequence1 = sequence(sequenceElement, options);
    
    speed
    • Type: a number representing milliseconds
    • Default: 500

    The speed at which steps should transition between one another when in fallback mode.

    API

    Sequence.js’ API allows you to use its properties, methods and callbacks to extend its functionality.

    Callbacks

    Callbacks allow you to execute custom JavaScript functions at specific key points during Sequence.js’ operation. For example, callbacks are executed every time the autoPlay feature is stopped/starting, allowing you to change the text of the autoPlay button for example.

    A callback can be accessed via the variable Sequence.js is saved in, like so:

      var sequenceElement = document.getElementById("sequence");
      var mySequence = sequence(sequenceElement);
    
      // When autoPlay is stopped
      mySequence.stopped = function() {
    
        // Add code to execute here, such as:
        alert("Sequence's auto play featured has been stopped");
      }
    
      // When Sequence is started
      mySequence.started = function() {
    
        // Add code to execute here, such as:
        alert("Sequence's auto play featured has been started");
      }
    

    stopped(sequence)

    Executed when autoPlay is stopped.

    • sequence: All properties and methods available to this instance

    started(sequence)

    Executed when autoPlay is started.

    • sequence: All properties and methods available to this instance

    animationStarted(id, sequence)

    Executed when a step animation starts.

    • id: The id of the step that started animating in
    • sequence: All properties and methods available to this instance

    animationEnded(id, sequence)

    Executed when a step animation ends (both the “in” and “out” phases finish).

    • id: The id of the step that finished animating

    currentPhaseStarted(id, sequence)

    Executed when the current phase starts animating out.

    • id: The id of the step the phase belongs to
    • sequence: All properties and methods available to this instance

    currentPhaseEnded(id, sequence)

    Executed when the current phase finishes animating out.

    • id: The id of the step the phase belongs to
    • sequence: All properties and methods available to this instance

    nextPhaseStarted(id, sequence)

    Executed when the next phase starts animating in.

    • id: The id of the step the phase belongs to
    • sequence: All properties and methods available to this instance

    nextPhaseEnded(id, sequence)

    Executed when the next phase finishes animating in.

    • id: The id of the step the phase belongs to
    • sequence: All properties and methods available to this instance

    throttledResize(sequence)

    Executed every 100 milliseconds when the browser window is resized.

    • sequence: All properties and methods available to this instance

    preloaded(sequence)

    Executed when Sequence has finished preloading.

    • sequence: All properties and methods available to this instance

    preloadProgress(result, src, progress, length, sequence)

    Executed for every image that Sequence.js preloads.

    • result: Whether the image is “loaded” or “broken”
    • src: The source of the image
    • progress: The number of images that have returned a result
    • length: The total number of images that are being preloaded

    Example use:

    sequence.preloadProgress = function(result, src, progress, length) {
    
      console.log( "image is " + result + " for " + src );
      console.log("progress: " + progress + " of " + length);
    }
    

    Example output to the web browser’s console:

    image is loaded for "images/smiley.gif"
    progress: 1 of 4
    

    ready(sequence)

    Executed when Sequence.js is deemed to be ready. This is executed after the preloaded() callback, plus an additional 50 milliseconds as defined via the domThreshold private variable in sequence.js. This callback can be used when you need to be certain Sequence.js has completely finished setting itself up, preloading, and manipulating the DOM. The additional 50 milliseconds is enough time for all DOM manipulations to complete.

    • sequence: All properties and methods available to this instance

    destroyed(sequence)

    Executed when Sequence.js is destroyed (removed from the element it is attached to and all Sequence.js functionality stopped) via the destroy() method.

    • sequence: All properties and methods available to this instance

    Methods

    Public methods are the functions that Sequence.js utilises, made available for developers to extend and enhance their particular instance.

    destroy()

    Remove Sequence.js from the element it is attached to and stop all Sequence.js functionality.

    goTo(id, direction, ignoreTransitionThreshold)

    Causes Sequence.js to animate to a specific step.

    • id (required): The ID of the step to go to
    • direction (optional): Direction to get to the step (1 = forward, -1 = reverse)
    • ignoreTransitionThreshold (optional): if true, ignore the phaseThreshold option and immediately go to the specified step.

    If a “direction” is not specified, Sequence.js will determine the shortest direction to the step and use that. For example, if cycle is enabled, going from step 1 to 4 will use a direction of -1, as going in reverse is the shortest direction.

    Examples:

    // Navigate forward to step 3
    sequence.goTo(3, 1);
    
    // Navigate in reverse to step 2
    sequence.goTo(2, -1);
    

    next()

    Causes Sequence.js to go to the next step.

    Example:

    sequence.next();
    

    prev()

    Causes Sequence.js to go to the previous step.

    Example:

    sequence.prev();
    

    start()

    Start Sequence.js’ autoPlay feature.

    Example:

    sequence.start();
    

    Note: even if autoPlay is disabled in the options, autoPlay can still later be enabled by using the start() method.

    stop()

    Stop Sequence.js’ autoPlay feature.

    Example:

    sequence.stop();
    

    toggleAutoPlay()

    Stop or start Sequence.js’ autoPlay feature based on its current state.

    Example:

    sequence.toggleAutoPlay();
    

    Note: even if autoPlay is disabled in the options, autoPlay can still later be enabled by using the toggleAutoPlay() method.

    utils

    utils (utilities) are cross browser helper functions that may be useful in custom theme code.

    The following functions are available under the utils property:

    addClass(elements, name)

    Cross browser function for adding classes to elements.

    Arguments:

    • elements – an HTML object
    • name – the class name you’d like to add to the element
    removeClass(elements, name)

    Cross browser function for removing classes from elements

    Arguments:

    • elements – an HTML object
    • name – the class name you’d like to remove from the element
    addEvent(element, eventName, handler)

    Cross browser function for adding events

    Arguments:

    • element – an HTML object
    • eventName – the name of the event, for example "click"
    • handler – the function to execute when the event occurs
    removeEvent(element, eventName, handler)

    Cross browser function for removing events

    Arguments:

    • element – an HTML object
    • eventName – the name of the event, for example "click"
    • handler – the handler to remove

    Properties

    Properties can be used to get certain information about the state of Sequence.js, for example, the ID of the current step.

    Properties can be taken from the variable the Sequence.js object is saved in to, like so:

      var sequenceElement = document.getElementById("sequence");
      var mySequence = sequence(sequenceElement);
    
      alert(mySequence.currentStepId);
    

    Or from the last argument of a callback:

      var sequenceElement = document.getElementById("sequence");
      var mySequence = sequence(sequenceElement);
    
      mySequence.started(sequence) = function() {
    
        alert(sequence.currentStepId);
      }
    

    Properties that hold elements or arrays containing elements are prefixed with $.

    $autoPlay

    • Type: Array
    • Dependencies: autoPlayButton: true | autoPlayButton: [css selector]

    Returns an array containing the HTML elements used as Sequence.js’ autoPlay button(s).

    $canvas

    • Type: HTMLElement

    Returns the HTML element used as Sequence.js’ canvas.

    $container

    • Type: HTMLElement

    Returns the HTML element used as Sequence.js’ container.

    $next

    • Type: Array
    • Dependencies: nextButton: true | nextButton: [css selector]

    Returns an array containing the HTML elements used as Sequence.js’ next button(s).

    $pagination

    • Type: Object
    • Dependencies: pagination: true | pagination: [css selector]

    Returns an object containing the HTML elements used as Sequence.js’ pagination and pagination links, as well as the ID of the Sequence.js element the pagination controls.

    Object properties:

    • relatedElementId – The ID/instance number of the Sequence.js element that pagination controls.
    • elements – An array containing the pagination elements associated with the Sequence.js instance
    • links – An array containing the pagination links that control the Sequence.js instance
    • currentLinks – An array containing the current pagination links

    $preloader

    • Type: Array
    • Dependencies: pagination: true | pagination: [css selector]

    Returns an array containing the HTML elements used as Sequence.js’ preloader(s).

    $prev

    • Type: Array
    • Dependencies: prevButton: true | prevButton: [css selector]

    Returns an array containing the HTML elements used as Sequence.js’ previous button(s).

    $steps

    • Type: Array

    Returns an array containing the HTML elements used as Sequence.js’ steps.

    currentStepId

    • Type: Number

    Returns a number representing the step that is currently being viewed.

    direction

    • Type: Number

    Returns a number representing the direction Sequence.js is last navigated in.

    firstRun

    • Type: True/false

    Returns true when Sequence.js is navigating to a step for the first time. False every time after

    • 1: Forward
    • -1: Reverse

    hammerTime

    • Type: Object

    Returns an object containing the Hammer event when the swipeNavigation option is enabled.

    isAnimating

    • Type: true/false

    Returns whether Sequence.js is currently animating.

    isAutoPlaying

    • Type: true/false

    Returns whether autoPlay is active. Note that autoplay is still active even if isAutoPlayPaused is true.

    isAutoPlayPaused

    • Type: true/false

    Returns whether autoPlay is paused. autoPlay is paused when the user hovers over the Sequence.js container and the autoPlayPauseOnHover is enabled.

    isFallbackMode

    • Type: True/False

    Returns true if Sequence.js is in fallback mode.

    isMouseOver

    • Type: True/False

    Returns true if the user’s cursor is over the container.

    isReady

    • Type: True/False

    Returns true when Sequence.js is ready. Sequence.js is ready after the preloaded() callback, plus an additional 50 milliseconds as defined via the domThreshold private variable in sequence.js.

    modernizr

    • Type: Object

    Returns Sequence.js’ custom build of Modernizr.

    navigationSkipThresholdActive

    • Type: true/false
    • Dependencies: navigationSkip: true

    Returns whether the navigationSkipThreshold is currently active (preventing the user from skipping steps).

    noOfSteps

    • Type: Number

    Returns the number of steps the Sequence.js instance is made up of.

    options

    • Type: Object

    Returns Sequence.js options – defaults combined with developer defined options.

    prevStepId

    • Type: Number

    Returns a number representing the step that was previously being viewed (the one before currentStepId).

    propertySupport

    • Type: Object

    An object containing the following properties:

    • animations: returns true when the browser supports CSS animations
    • transitions: returns true when the browser supports CSS transitions

    stepsAnimating

    • Type: Number

    Returns the number of steps that are currently animating.

    stepProperties

    • Type: Object

    Returns an object used by Sequence.js to know how many steps it will consist of, the elements that will animate, and their durations.