smoothState.js: Unobtrusive page transitions with jQuery.

We’ve accepted the jankiness of page loads as a quirk of the web even though there is no technical reason for it. smoothState.js lets you add transitions to eliminate the hard cuts and white flashes of page loads that deface the beauty of the user experience.

SmoothState.js is a jQuery plugin that progressively enhances page loads to give us control over page transitions. If the user’s browser doesn’t have the required features, smoothState.js fades into the background and never runs.

Why are page transitions necessary?

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 for the user to adjust. Smooth transitions reduce the effort it takes for users to get settled into a new environment.

Javascript SPA frameworks, sometimes referred to as MVC frameworks, are a common way to solve this issue. These frameworks often lose the benefits of unobtrusive code. Writing unobtrusive javascript gives us more resilience to errors, and improved performance and accessibility.

How does smoothState.js work?

smoothState.js provides hooks that can be used to choreograph how elements enter and exit the page during navigation. It uses the time the animations are running to fetch content via AJAX to inject into the page.

smoothState.js doesn’t dictate how things on the page should be animated. It supports CSS animations, as well as JS animation libraries like velocity.js.

Design philosophy and requirements

The project’s main goal is to allow developers to add page transitions without having to add any logic to the backend. We keep things unobtrusive at all times.

smoothState.js initializes on containers, not links. Think of a container as a small window object embedded in the page.

Every URL on your site should return a full layout – not just an HTML fragment
The smoothState container needs to have an id set – a unique hook to tell us what to update on the page
All links and forms on the page should live within the container
These requirements makes the website resilient, since it smoothState.js can abort and simply redirect the user if an error occurs. Making each link return a full page also ensures that pages are created with progressive enhancement in mind.

Illustration by akselkreis