Web Navigation Transitions

Editor’s Draft,

This version:
http://cwiiis.github.io/gaia-navigator/
Editor:
(Mozilla)

Abstract

This specification describes a mechanism that allows animations to be performed between page navigations using style sheets, and optionally, JavaScript.

Table of Contents

1. Introduction

Web Navigation Transitions defines an interface and behaviour that allows animations to be performed when the user agent navigates from one location to another. This animation can involve both the existing document and the new document, allowing for transitions that visually involve both documents simultaneously.

1.1. Use cases

The use cases for the specification include the following:

Cross-fading a new page on load

A page may want to fade in on top of the previous page to make the navigation transition less jarring. The programming interface in this specification allows such an effect using just CSS on the destination page.

@navigation-transition enter 0.5s {
  html {
    background-color: transparent;
    animation: fade-in 0.5s;
  }
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

Sliding a new page in from the right

A page may want to slide in from the right to give the user an idea of space when navigating a site.

@navigation-transition enter 0.2s {
  html {
    background-color: transparent;
    animation: slide-in 0.2s;
  }
}

@keyframes slide-in {
  from { transform: translateX(100%); }
}

The previous page may want to slide away to the left during this transition, which can be done with an exit transition.

@navigation-transition exit 0.2s {
  html {
    background-color: transparent;
    animation: slide-out 0.2s;
  }
}

@keyframes slide-out {
  to { transform: translateX(-100%); }
}

Fading a page while loading

A page may want to fade slightly to indicate to the user that it is not interactive while loading a new page.

@navigation-transition exit 0.2s immediate {
  html {
    animation: fade 0.5s both;
  }
}

@keyframes fade {
  to { opacity: 0.3; }
}

The destination page could also fade in to complete the effect.

2. The @navigation-transition rule

The @navigation-transition at-rule consists of the @-keyword followed by any navigation transition properties and finally a block of style rules to apply during the defined navigation transition.

2.1. Syntax

The syntax for the @navigation-transition rule is as follows:

navigation-transition navigation-transition-type navigation-transition-duration [ navigation-transition-start ] [ navigation-transition-z-index ]

Name: navigation-transition-type
For: @navigation-transition
Value: <single-navigation-transition-type>#
Initial: enter

<single-navigation-transition-type> = enter | exit

The values of navigation-transition-type have the following meanings:

enter
This navigation transition is for when a page has been navigated to.
exit
This navigation transition is for when a page has been navigated away from.
Name: navigation-transition-duration
For: @navigation-transition
Value: <time>#
Initial: 0s
<time>
The <time> specifies the length of time that a navigation transition applies for. A negative <time> is invalid.

If the <time> is 0s, the style of the transition will not be applied, but the transition itself still occurs instantaneously. Specifically, start and end events are fired.

Name: navigation-transition-start
For: @navigation-transition
Value: <single-navigation-transition-start>#
Initial: on-load

<single-navigation-transition-start> = on-load | immediate

The values of navigation-transition-start have the following meanings:

on-load
The transition will apply once the page has loaded. Specifically, after the load event associated with the page is emitted.
immediate
The transition will apply immediately after the page navigation is initiated.
Name: navigation-transition-z-index
For: @navigation-transition
Value: <integer>#
Initial: 0
<integer>
Assigns the page a z-ordering priority for when transitions on two pages happen simultaneously.

3. Starting navigation transitions

Navigation transitions can start either immediately, or after the window has emitted the load event associated with the page, as specified by the navigation-transition-start property. If a page has no navigation transition specified and a page is navigated to that has navigation transitions, it will remain on screen for the duration of the longest transition specified on the transitioning page. During navigation transitions, a page will remain in the window and the style rules specified in the @navigation-transition block will apply. The page that is being navigated to will be drawn on top of the page being navigated from, unless otherwise specified by the navigation-transition-z-index property. This is unrelated to an individual element’s z-index, each page is drawn entirely in its particular order and cannot interleave contents with the other page.

A navigation transition’s at rule will apply for the specified duration of the navigation transition. Once that duration has elapsed, the style block associated with the at-rule will no longer apply. If all navigation transition durations have elapsed and the page is being navigated from, the page will unload, similarly to if no navigation transition had been specified and the page had been navigated from.

3.1. Multiple navigation transitions

In the situation that multiple navigation transitions are specified on a single page, all associated rules will apply, in the order in which they were defined. The page will stay loaded until all navigation transitions have completed.

When navigating backwards, animations are also run backwards, as specified in the Web Animations specification. In addition, the page being navigated backwards to will be drawn underneath the page being navigated from, unless otherwise specified by the navigation-transition-z-index property.

3.3. Interrupting a navigation transition

If the user agent needs to interrupt a navigation transition, for example, due to the user interrupting the page loading by navigating elsewhere, or by stopping transfers, all navigation transitions style rules will immediately stop applying. The navigationtransitionend event will be emitted if any transitions were interrupted.

If a navigation transition that was scheduled to start on a page load via navigation-transition-start is interrupted, navigation transitions will stop applying, the page that was navigated from will unload and the new page will be displayed.

The CSSRule interface is extended as follows:

partial interface CSSRule {
  const unsigned short NAVIGATION_TRANSITION_RULE = 1002;
};

The CSSNavigationTransitionRule interface represents a @navigation-transition rule.

interface CSSNavigationTransitionRule : CSSGroupingRule {
  attribute NavigationTransitionType type;
  attribute DOMString duration;
  attribute NavigationTransitionStart start;
  attribute long zIndex;
};

enum NavigationTransitionType { "enter", "exit" };
enum NavigationTransitionStart { "on-load", "immediate" };

Navigation transition-related events are available through the DOM Event system. The start and end of a navigation transition generates DOM events. A page can have multiple navigation transitions operating simultaneously. One navigationtransitionstart event will be emitted when the first navigation transition starts, and one navigationtransitionend event will be emitted when the last navigation transition ends.

5.1. The NavigationTransitionEvent interface

The NavigationTransitionEvent interface provides specific contextual information associated with Navigation Transition events.

5.1.1. IDL Definition

[Constructor(DOMString type, optional NavigationTransitionEventInit navigationTransitionEventInitDict)]
interface NavigationTransitionEvent : Event {
  readonly attribute DOMString navigationTransitionType;
};
dictionary NavigationTransitionEventInit : EventInit {
  DOMString navigationTransitionType = "enter";
};

5.1.2. Attributes

navigationTransitionType, of type , of type DOMString, readonlyDOMString, readonly
A string representing the type of navigation transition. Can take one of four values; enter, enter-back, exit or exit-back.

5.2. Types of NavigationTransitionEvent

The different types of navigation transition events that can occur are:

navigationtransitionstart
The navigationtransitionstart event occurs at the start of the first transition.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: navigationTransitionType
navigationtransitionend
The navigationtransitionend event occurs at the end of the last transition.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: navigationTransitionType

A page’s navigationtransitionstart event will be fired after the first @navigation-transition block is applied, as specified by navigation-transition-start. This event will be fired before the first paint after the block is applied. A page’s navigationtransitionend event will be fired after the duration specified by navigation-transition-duration. Although a navigation transition causes a page’s lifetime to extend to the duration of that transition, the page’s beforeunload event is unaffected and will fire before navigationtransitionstart.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[WebIDL]
Cameron McCormack. Web IDL. 19 April 2012. CR. URL: http://www.w3.org/TR/WebIDL/
[CSS-VALUES-3]
CSS Values and Units Module Level 3 URL: http://www.w3.org/TR/css3-values/
[CSSOM-1]
CSS Object Model Level 1 URL: http://www.w3.org/TR/cssom/
[DOM-LS]
Document Object Model URL: http://dom.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Property Index

No properties defined.

Name Value Initial
navigation-transition-type <single-navigation-transition-type># enter
navigation-transition-duration <time># 0s
navigation-transition-start <single-navigation-transition-start># on-load
navigation-transition-z-index <integer># 0

IDL Index

partial interface CSSRule {
  const unsigned short NAVIGATION_TRANSITION_RULE = 1002;
};

interface CSSNavigationTransitionRule : CSSGroupingRule {
  attribute NavigationTransitionType type;
  attribute DOMString duration;
  attribute NavigationTransitionStart start;
  attribute long zIndex;
};

enum NavigationTransitionType { "enter", "exit" };
enum NavigationTransitionStart { "on-load", "immediate" };

[Constructor(DOMString type, optional NavigationTransitionEventInit navigationTransitionEventInitDict)]
interface NavigationTransitionEvent : Event {
  readonly attribute DOMString navigationTransitionType;
};
dictionary NavigationTransitionEventInit : EventInit {
  DOMString navigationTransitionType = "enter";
};