Powerful Page Transition Plugin - jQuery smoothState

File Size: 92.2 KB
Views Total: 1290
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Powerful Page Transition Plugin - jQuery smoothState

When building an application or site, transitioning between pages is an important design aspect to consider. From a UX perspective, transitions are used to guide and direct the visitor's eye. They also provide consistency in the overall experience giving each page a unique personality. 

SmoothState is a progressively enhanced jQuery plugin that adds smooth and configurable transitions to your site when navigating between pages. SmoothState is lightweight and simple, yet packs tons of features:


  • Uses AJAX to fetch pages.
  • Auto updates URLs and browsing history.
  • Works with CSS3 animations and 3rd-party animation libraries.
  • Allows to prefetch page content when hovering over links.
  • Also works with anchor links.

See Also:

How to use it:

1. Load the minified version of the smoothState jQuery plugin.

<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/jquery.smoothState.min.js"></script>

2. Add page content to a wrapper element with an uniue ID.

<div id="wrapper">
  Page Content 

3. Add your own CSS or JavaScript powered transitions to page using the following callbacks.

const options = {

      // before loading a page
      onBefore: function($currentTarget, $container) {},

      // when starting loading a page
      onStart: {
        // How long this animation takes
        duration: 0,
        // A function that dictates the animations that take place
        render: function ($container) {}

      // when loading a page
      onProgress: {
        // How long this animation takes
        duration: 0,
        // A function that dictates the animations that take place
        render: function ($container) {}

      // when the page is ready
      onReady: {
        duration: 0,
        render: function ($container, $newContent) {
          // Update the HTML on the page

      // after the page is loaded
      onAfter: function($container, $newContent) {}

4. Initialize the smoothState.

smoothState = $('#wrapper').smoothState(options).data('smoothState');

5. More plugin options.

/** If set to true, smoothState will log useful debug information instead of aborting */
debug: false,

/** jQuery selector to specify which anchors smoothState should bind to */
anchors: 'a',

/** Regex to specify which href smoothState should load. If empty, every href will be permitted. */
hrefRegex: '',

/** jQuery selector to specify which forms smoothState should bind to */
forms: 'form',

/** If set to true, smoothState will store form responses in the cache. */
allowFormCaching: false,

/** Minimum number of milliseconds between click/submit events. Events ignored beyond this rate are ignored. */
repeatDelay: 500,

/** A selector that defines what should be ignored by smoothState */
blacklist: '.no-smoothState',

/** If set to true, smoothState will prefetch a link's contents on hover */
prefetch: false,

/** The name of the event we will listen to from anchors if we're prefetching */
prefetchOn: 'mouseover touchstart',

/** jQuery selector to specify elements which should not be prefetched */
prefetchBlacklist: '.no-prefetch',

/** The response header field name defining the request's final URI. Useful for resolving redirections. */
locationHeader: 'X-SmoothState-Location',

/** The number of pages smoothState will try to store in memory */
cacheLength: 0,

/** Class that will be applied to the body while the page is loading */
loadingClass: 'is-loading',

/** Scroll to top after onStart and scroll to hash after onReady */
scroll: true,

 * A function that can be used to alter the ajax request settings before it is called
 * @param  {Object} request - jQuery.ajax settings object that will be used to make the request
 * @return {Object}         Altered request object
alterRequest: function (request) {
  return request;

 * A function that can be used to alter the state object before it is updated or added to the browsers history
 * @param  {Object} state - An object that will be assigned to history entry
 * @param  {string} title - The history entry's title. For reference only
 * @param  {string} url   - The history entry's URL. For reference only
 * @return {Object}         Altered state object
alterChangeState: function (state, title, url) {
  return state;

6. Initialize the smoothState.

// load a page into the current container

// fetch content from a specific page

// clear the page from the cache

// restart CSS animations

This awesome jQuery plugin is developed by miguel-perez. For more Advanced Usages, please check the demo page or visit the official website.