smoothState.js is a jQuery plugin that progressively enhances page loads to give us control over page transitions. If the user’s browser does not have the needed features, it quietly fades into the background and never runs.
Why add page transitions at all?
Imagine, for a second, how disorienting it would be if touching a doorknob teleported you to the other side of the door. Navigating the web feels like using a teleporting doorknob. Layouts change, elements rearrange or disappear, and it takes time time for the user to adjust. Smooth transitions reduce the effort it takes for users to get settled into a new environment.
Hows does smoothState.js work?
smoothState.js gives you hooks that you can use in order to choreograph how the elements on your page enter and exit the page. It allows you to specify how long your animations take, and it uses the time in between animations to fetch content via Ajax.
This project doesn’t dictate how you should animate things on the page. It supports CSS Animations, and allows for any popular JS animation library like velocity.js.
Design philosophy and requirements
It’s our main goal to allow us to add page transitions without having to add any logic to the backend. We keep things unobtrusive at all times.
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 url on your site should return a full layout - not just an HTML fragment
- The smoothState container needs to have an id - a unique hook to tell us what to update on the page
- All links and forms on the page should reside within the container
These requirements makes the website 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.
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
- Add container with an id of
#mainand include some links inside of it
By default, smoothState.js will:
- Prevent links and forms 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 appropriate content
This default example will not add page transitions to your page. You’ll need to define the animations you’ll want to run using the hooks smoothState provides.
- onBefore - Runs before a page load has been activated
- onStart - Runs when a page load has been activated
- onProgress - Runs if the page request is still pending and onStart has finished animating
- onReady - Run when requested content is ready to be injected into the page and the previous animations have finished
- onAfter - Runs after content has been injected into the page and all animations are complete
smoothState provides some options that allow you to customize the functionality of the plugin. You can change the default options by passing in an object into the smooth state function.
If set to true, smoothState will log useful debug information instead of aborting. For example, instead of redirecting the user to a page on an error, it might say:
No element with an id of “#main” in response from “/about.html”.
A jQuery selector to specify which anchors within the smoothState element we should listen should bind to.
A jQuery selector to specify which forms within the smoothState element we should listen should bind to.
A jQuery selector to specify which elements within the smoothState element we should completely ignore. This will apply for both forms and anchors.
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
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 increase the perceived performance of your website.
smoothState.js will store pages in memory if cacheLength is set to anything greater than 0. This allows a user to avoid having to request pages more than once.
Pages that are stored will load instantaneously.
Class that will be applied to the body while the page is loading. We we get the page before the animations are complete, however, the loadingClass will never be added.
A function that can be used to alter the ajax settings before it is requested. This is useful when dealing with applications that have layout controls or when needing to invalidate the cache.
This function runs before a page load has been activated.
This function runs when a page load has been activated. This is an ideal time to animate elements that exit the page and set up for a loading state.
Run only if the page request is still pending and onStart has finished animating. This is a good place to add something like a loading indicator.
Objectwith two properties,
Run when requested content is ready to be injected into the page. This is when we’ll want to update the page’s content.
This function runs when content has been injected and all animations are complete. This is when we want to re-initialize any plugins on the page.
Methods and properties
smoothState provides some methods available by accessing the element's data property.
// Access smoothStatevar smoothState = data‘smoothState’;// Run methodsmoothState;
The methods and properties available are:
Url of the content that is currently displayed.
Loads the contents of a url into our container.
Variable that stores pages after they are requested.
Fetches the contents of a url and stores it.
Clears a given page from the cache, if no url is provided it will clear the entire cache.
Restarts the CSS animations of the smoothState container.
If you need a little help implementing smoothState there are a couple things you could do to get some support:
- Post on stackoverflow using the smoothState.js tag.
- Join the Gitter room and talk to some of the contributors.
- Contact Miguel, he provides training and consultation services.
Please avoid creating a Github issue with personal support requests, we'll want to keep the tracker clear for bugs and pull requests.
We're always looking for:
- Bug reports, especially those with a reduced test case
- Pull requests, features, spelling errors, clarifications, etc
- Ideas for enhancements
- Demos and links to sites built with smoothState.js