Page Transition Plugins

Overview

The jQuery Mobile (post 1.0a4.1) page transitions code was modified to allow developers to create their own custom transitions and/or override existing transitions. This document describes how a developer can create his/her own custom CSS3 or JavaScript based transitions.

Pure CSS3 Based Transitions

Up until jQuery Mobile 1.0a4.1, the only way to add a custom page transition was to implement it via CSS, leveraging CSS3 transitions or animation keyframes.

To add a new CSS transition of your own, all you have to do is select a class name that corresponds to the name of your transition, for example "slide", and then define your "in" and "out" CSS rules to take advantage of transitions or animation keyframes:

.slide.in {
    -webkit-transform: translateX(0);
    -webkit-animation-name: slideinfromright;
}

.slide.out {
    -webkit-transform: translateX(-100%);
    -webkit-animation-name: slideouttoleft;
}

@-webkit-keyframes slideinfromright {
    from { -webkit-transform: translateX(100%); }
    to { -webkit-transform: translateX(0); }
}
@-webkit-keyframes slideouttoleft {
    from { -webkit-transform: translateX(0); }
    to { -webkit-transform: translateX(-100%); }
}

During a CSS based page transition, jQuery Mobile will place the class name of the transition on both the "from" and "to" pages involved in the transition. I then places an "out" class on the "from" page, and "in" class on the "to" page. The presence of these classes on the "from" and "to" page elements then triggers the animation CSS rules defined above.

If your transition supports a reverse direction, you will need to create CSS rules that use the "reverse" class in addition to the transition class name and the "in" and "out" classes:

.slide.in.reverse {
    -webkit-transform: translateX(0);
    -webkit-animation-name: slideinfromleft;
}

.slide.out.reverse {
    -webkit-transform: translateX(100%);
    -webkit-animation-name: slideouttoright;
}

@-webkit-keyframes slideinfromleft {
    from { -webkit-transform: translateX(-100%); }
    to { -webkit-transform: translateX(0); }
}

@-webkit-keyframes slideouttoright {
    from { -webkit-transform: translateX(0); }
    to { -webkit-transform: translateX(100%); }
}

After you rules are in place, you simply specify the name of your transition within the @data-transition attribute of a navigation link:

<a href="#page2" data-transition="slide">Page 2</a>

When the user clicks on the navigation link, jQuery Mobile will then invoke your transition when it navigates to the page mentioned within the link.

In case you were wondering why none of the CSS rules above specified any easing or duration, it's because the CSS for jQuery Mobile defines the default easing and duration in the following rules:

.in, .out {
    -webkit-animation-timing-function: ease-in-out;
    -webkit-animation-duration: 350ms;
}

If you need to specify a different easing or duration, simply add the appropriate CSS3 property to your custom page transition rules.

JavaScript Based Transitions

When a user clicks on a link within a page, the navigation code in jQuery Mobile checks to see if the link specifies a @data-transition attribute. The value within this attribute is the name of the transition to use when displaying the page referred to by the link. If there is no @data-transition attribute, the default transition name specified by the configuration option $.mobile.defaultTransition is used.

After the new page is loaded, the $.mobile.transitionHandlers dictionary is used to see if any transition handler function is registered for the given transition name. If a handler is found, that handler is invoked to start and manage the transition. If no handler is found the handler specified by the configuration option $.mobile.defaultTransitionHandler is invoked.

By default, the $.mobile.transitionHandlers dictionary is only populated with a single handler entry called "none". This handler simply removes the "ui-page-active" class off of the page we are transitioning "from", and places it on the page we are transitioning "to". The transition is instantaneous, no animation, no fan-fare.

The $.defaultTransitionHandler is set to point to a handler function that assumes any name you give it is a CSS class name, and performs all of the functionality mentioned in the "Pure CSS3 Based Transitions" section above.

Both the "none" and "css3" transition handlers are available off of the $.mobile namespace:

$.mobile.noneTransitionHandler
$.mobile.css3TransitionHandler

Transition Handlers

A transition handler is a simple function with the following call signature:

function myTransitionHandler(name, reverse, $to, $from)
{
    var deferred = new $.Deferred();

    // Perform any actions or set-up necessary to kick-off
    // your transition here. The only requirement is that
    // whenever the transition completes, your code calls
    // deferred.resolve(name, reverse, $to, $from).

    // Return a promise.
    return deferred.promise();
}

Your handler must create a Deferred object and return a promise to the caller. The promise is used to communicate to the caller when your transition is actually complete. It is up to you to call deferred.resolve() at the correct time. If you are new to Deferred objects, you can find documentation here.