Checkout the demo site for examples and tutorials. Let me know if you have any questions.

• About
• Options
  • prefetch
  • blacklist
  • development
  • pageCacheSize
  • alterRequestUrl
• Callbacks
  • onStart
  • onProgress
  • onEnd
  • callback
• Methods and properties
  • href
  • cache
  • load
  • fetch
  • toggleAnimationClass
• Show your work!
• Need help?

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.

smoothState provides some options that allow you to customize the functionality of the plugin.

There is a 200ms to 300ms delay between the time that a user hovers over a link and the time they click it. On touch screens, the delay between the touchstart and touchend is even greater. If the prefetch option is set to true, smoothState will begin to preload the contents of the url between that delay.

This technique will dramatically increase the speed of your website.

A string that is used as a jQuery selector to ignore certain links. By default smoothState will ignore any links that match ".no-smoothstate, [target]".

A boolean, default being false, that will tell smoothState to output useful debug info when something goes wrong in console instead of trying to abort and reload the page.

smoothState.js will store pages in memory if pageCacheSize is set to anything greater than 0. This allows a user to avoid having to request pages more than once. Pages that are stored in memory will load instantaneously.

A function that defines any alterations needed on the URL that is used to request content from the server. The function should return a string that is a valid URL. This is useful when dealing with applications that have layout controls or when needing to inavlidate the cache.

Ran when a link has been activated, a "click". Default:

onStart : {
    duration: 0, // Duration of the animations, if any.
    render: function (url, $container) {
        $body.scrollTop(0);
    }
},

Ran if the page request is still pending and onStart has finished animating.Default:

onProgress : {
    duration: 0, // Duration of the animations, if any.
    render: function (url, $container) {
        $body.css('cursor', 'wait');
        $body.find('a').css('cursor', 'wait');
    }
},

Ran when requested content is ready to be injected into the page

onEnd : {
    duration: 0, // Duration of the animations, if any.
    render: function (url, $container, $content) {
        $body.css('cursor', 'auto');
        $body.find('a').css('cursor', 'auto');
        $container.html($content);
    }
},

Ran after the new content has been injected into the page

callback : function(url, $container, $content) {

}

smoothState provides some methods available by accessing the element's data property.

var content  = $('#main').smoothState().data('smoothState');
content.load('/newPage.html');

Url of the content that is currently displayed.

Variable that stores pages after they are requested.

Loads the contents of a url into our container.

Fetches the contents of a url and stores it in the 'cache' varible.

Used to restart css animations with a class.

I'd love to see how this gets used in the wild. Tweet me with a link and I'll add it to this page. This repo could use some good demos.

If you find yourself confused, add an issue explaining your problem. Doing so will help me improve the clarity of the documentation and get us thinking about use cases and potential upgrades. I'm all ears.