Get started with smoothState.js - jQuery.smoothState.js

← jquery.smoothState.js

An introduction to the fundamentals of smoothState.js, including an explanation of the code's approach, requirements, and default behavior. The benefits of this plugin are also covered here.

Why use smoothState.js?

Hard cuts and white flashes break user focus and create confusion as layouts change or elements rearrange. We’ve accepted the jankiness of page loads as a personality quirk of the web, even though there is no technical reason it must exist. We don't need to treat the web like a native app's ugly cousin.

Javascript SPA frameworks, sometimes referred to as MVC frameworks, are a common way to solve this issue. However, these frameworks often lose the benefits of unobtrusive code, such as resilience to errors, performance, and accessibility. smoothState.js lets you start adding transitions that eliminate the hard cuts of page loads to improve the beauty of the experience. It does this with:

Progressive enhancement - a technique that exemplifies the principles universal design
jQuery - a library a great many of us are familiar with
history.pushState() - a method that lets us maintain browsing expectations
Ajax - a way for us to request and store pages on the user's device without refreshing the page

smoothState.js will unobtrusively enhance your website's page loads to behave more like a single-page application framework. This allows you to add page transitions and create a nicer experince for your users.

Requirements

smoothState.js is initialized on containers, not links. The containers can be thought of like small window objects within the page, similar to how you would describe an iframe.

Every container needs to have an id - a unique hook to tell the smoothState.js what to update on the page
Every link should return a full layout - not just an HTML fragment

This requirement makes the website more resilient since it allows us to abort and redirect the user if an error occurs. Making each link return a fully qualified page also ensures our page transitions are unobtrusive.

There may be a rare case when returning a full layout is not desired. smoothState.js will still function properly as long as the container being updated is present in the response from the server. If you're having issues with this, turn on development mode and watch the console for useful warnings.

A barebones example

All we need to get started is:

Include a copy of jQuery and jQuery.smoothState.js on your page
Create a new js file and run $('#main').smoothState()
Add container with an id of "#main" and include some links inside of it

The HTML

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Home - My Site</title>
  </head>
  <body>
    <!-- Every smoothState container needs an id -->
    <div id="main">
      <!-- Every link should return a full layout -->
      <ul>
        <li><a href="index.html">Home</a></li>
        <li><a href="about.html">About</a></li>
      </ul>
      <!-- Contents of the page... -->
    </div>
    <!-- Scripts -->
    <script src="jquery.js"></script> 
    <script src="jquery.smoothState.js"></script>
    <script src="functions.js"></script>
  </body>
</html>

The JS

// Contents of functions.js
;(function ($) {
    $('#main').smoothState();
})(jQuery);

You can see a demo of the this basic example and interact with the pages. By default, smoothState.js will:

Prevent links from triggering a full page load
Update the user's URLs and history as to not break browsing expectations
Use Ajax to request pages and replace the appropiate content

This default example will not add page transitions to your page. See a typical implementation for an example of how to add a simple fade effect on your site. If you're feeling ambitious, check out an advanced example or go read the documentation.