Web Navigation Transitions

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 ]

2.1.1. navigation-transition-type

<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.

2.1.2. navigation-transition-duration

<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.

2.1.3. navigation-transition-start

<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.

2.1.4. navigation-transition-z-index

<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.

3.2. Navigating backwards

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.

4. CSSOM

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" };

5. Navigation transition events

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

5.3. Ordering

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.