Fullscreen API

Living Standard — Last Updated 1 August 2014

This Version:
http://fullscreen.spec.whatwg.org/
Participate:
Send feedback to whatwg@whatwg.org (archives) or file a bug (open bugs)
IRC: #whatwg on Freenode
Version History:
https://github.com/whatwg/fullscreen/commits
@FullscreenAPI
Editors:
Anne van Kesteren (Mozilla) <>
Tantek Çelik (Mozilla) <>

Abstract

Fullscreen defines the fullscreen API for the web platform.

Table of Contents

  1. 1 Conformance
  2. 2 Terminology
  3. 3 Model
  4. 4 API
  5. 5 UI
  6. 6 Rendering
    1. 6.1 New stacking layer
    2. 6.2 ::backdrop pseudo-element
    3. 6.3 :fullscreen pseudo-class
    4. 6.4 User-agent level style sheet defaults
  7. 7 Security and Privacy Considerations
  8. References
  9. Acknowledgments

1 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

2 Terminology

Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [CSS] [DOM] [HTML] [WEBIDL]

The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.

A browsing context A is called a descendant browsing context of a browsing context B if and only if B is an ancestor browsing context of A.

3 Model

The task source used by this specification is the user interaction task source.

All documents have an associated fullscreen enabled flag and fullscreen element stack. Unless otherwise stated the fullscreen enabled flag is unset and the fullscreen element stack is an initially empty ordered set.

HTML defines the exact conditions under which the fullscreen enabled flag is set. A document from a top-level browsing context will have it set. For a nested browsing context it is only set if the iframe element that is responsible for creating the nested browsing context has its allowfullscreen attribute set. That attribute is defined by HTML as well. [HTML]

To add an element on a document's fullscreen element stack, add, or move if already present, it on top of document's browsing context's top layer, and then add, or move if already present, it on top of document's fullscreen element stack.

To remove an element from a document's fullscreen element stack, remove it from document's browsing context's top layer, and then remove it from document's fullscreen element stack.

To empty a document's fullscreen element stack, remove all the elements in it from document's browsing context's top layer, and then empty document's fullscreen element stack.


To fully exit fullscreen, run these steps:

  1. Let doc be the top-level browsing context's document.

  2. Remove elements from doc's fullscreen element stack until there is one element left.

  3. Act as if the exitFullscreen() method was invoked on doc.

HTML invokes the fully exit fullscreen algorithm for navigation. [HTML]

If an element at the top of a fullscreen element stack is removed from a document, act as if the exitFullscreen() method was invoked on that document.


Fullscreen is supported if there is no previously-established user preference, security risk, or platform limitation.

4 API

partial interface Element {
  void requestFullscreen();
};

partial interface Document {
  readonly attribute boolean fullscreenEnabled;
  readonly attribute Element? fullscreenElement;

  void exitFullscreen();

  attribute EventHandler onfullscreenchange;
  attribute EventHandler onfullscreenerror;
};
element . requestFullscreen()

Displays element fullscreen.

document . fullscreenEnabled

Returns true if document has the ability to display elements fullscreen and fullscreen is supported, or false otherwise.

document . fullscreenElement

Returns the element that is displayed fullscreen, or null if there is no such element.

document . exitFullscreen()

Stops any elements within document from being displayed fullscreen.

A fullscreen element ready check for an element returns true if all of the following are true, and false otherwise:

The requestFullscreen() method must run these steps:

  1. Let pending be the context object.

  2. Let error be false.

  3. If any of the following conditions are true, set error to true:

  4. Let fullscreenElements be a set initially consisting of pending.

  5. Let topLevelViewport be pending's top-level browsing context's document's viewport.

  6. If error is false: While the first element in fullscreenElements is in a nested browsing context, prepend its browsing context container to fullscreenElements.

  7. Return, and run the remaining steps asynchronously.

  8. If error is false: Resize topLevelViewport's dimensions to match the dimensions of the screen of the output device. Optionally display a message how the end user can revert this.

  9. As part of the next animation frame task, run these substeps for each element element in fullscreenElements, in order:

    1. Let doc be element's node document.

    2. If either error is true or the fullscreen element ready check for element returns false, fire an event named fullscreenerror on doc, and then terminate these steps.

    3. If element is on top of doc's fullscreen element stack, terminate these substeps.

      No need to notify observers when nothing has changed.

    4. Add element on doc's fullscreen element stack.

    5. Fire an event named fullscreenchange on doc.

    Animation frame task is not really defined yet, including relative order within that task, see bug 26440.

    Implementations with out-of-process browsing contexts are left as an exercise to the reader. Input welcome on potential improvements.

The fullscreenEnabled attribute must return true if the context object has its fullscreen enabled flag set and fullscreen is supported, and false otherwise.

The fullscreenElement attribute must return the top element of the context object's fullscreen element stack, and null otherwise.

The exitFullscreen() method must run these steps:

  1. Let doc be the context object.

  2. Return, and run the remaining steps asynchronously.

  3. As part of the next animation frame task, run these substeps:

    1. If doc's fullscreen element stack is empty, terminate these steps.

    2. Let descendants be all the doc's descendant browsing context's documents with a non-empty fullscreen element stack (if any), in tree order.

    3. For each descendant in descendants, empty descendant's fullscreen element stack and fire an event named fullscreenchange on descendant.

    4. Then, while doc is not null, run these subsubsteps:

      1. Let lastDoc be doc.

      2. If doc's fullscreen element stack is empty and doc's browsing context has a browsing context container, set doc to that browsing context container's node document, and to null otherwise.

      3. Remove the top element of doc's fullscreen element stack.

        If doc's fullscreen element stack is non-empty and the element now at the top is either not in a document or its node document is not doc, run this subsubstep again.

        This is needed because a non-top element in the fullscreen element stack could have been removed from doc.

      4. Fire an event named fullscreenchange on lastDoc.

    5. Let topLevelDoc be doc's top-level browsing context's document.

    6. If topLevelDoc's fullscreen element stack is empty, asynchronously resize topLevelDoc's viewport to its "normal" dimensions.


The following are the event handlers (and their corresponding event handler event types) that must be supported on documents as attributes:

event handler event handler event type
onfullscreenchange fullscreenchange
onfullscreenerror fullscreenerror

5 UI

User agents are encouraged to implement native media fullscreen controls in terms of requestFullscreen() and exitFullscreen().

If the end user instructs the user agent to end a fullscreen session initiated via requestFullscreen(), fully exit fullscreen.

6 Rendering

This section is to be interpreted equivalently to the Rendering section of HTML. [HTML]

Long term CSS will define the top layer concept and its associated ::backdrop pseudo-element as part of CSS' stacking context model. Patching CSS as done here is sketchy as hell.

6.1 New stacking layer

This specification introduces a new stacking layer to the Elaborate description of Stacking Contexts of CSS 2.1. It is called the top layer, comes after step 10 in the painting order, and is therefore rendered closest to the user within a viewport. Each browsing context has one associated viewport and therefore also one top layer. [CSS]

The terminology used in this and following subsection attempts to match CSS 2.1 Appendix E.

The top layer consists of an ordered set of elements, rendered in the order they have been added to the set. The last element added is rendered closest to the user.

The z-index property has no effect in the top layer.

An element in a top layer has the following characteristics:

6.2 ::backdrop pseudo-element

Each element in a top layer has a ::backdrop pseudo-element. This pseudo-element is a box rendered immediately below the element (and above the element before the element in the set, if any), within the same top layer. This pseudo-element box has the same characteristics as any element box in the top layer.

The ::backdrop pseudo-element can be used to create a backdrop that hides the underlying document for an element in a top layer (such as an element that is displayed fullscreen).

It does not inherit from any element and is not inherited from. No restrictions are made on what properties apply to this pseudo-element either.

6.3 :fullscreen pseudo-class

The :fullscreen pseudo-class must match the top element of the document's fullscreen element stack (if any).

6.4 User-agent level style sheet defaults

@namespace "http://www.w3.org/1999/xhtml";

*|*:not(:root):fullscreen {
  position:fixed;
  top:0; right:0; bottom:0; left:0;
  margin:0;
  box-sizing:border-box;
  width:100%;
  height:100%;
  object-fit:contain;
}

iframe:fullscreen {
  border:none;
}

*|*:fullscreen::backdrop {
  position:fixed;
  top:0; right:0; bottom:0; left:0;
  background:black;
}

7 Security and Privacy Considerations

User agents should ensure, e.g. by means of an overlay, that the end user is aware something is displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and advertise this to the user. This is to prevent a site from spoofing the end user by recreating the user agent or even operating system environment when fullscreen. See also the definition of requestFullscreen().

To enable content in a nested browsing context to go fullscreen, it needs to be specifically allowed via the allowfullscreen attribute of the HTML iframe element. This prevents e.g. content from third parties to go fullscreen without explicit permission.

References

[CSS]
CSS, Bert Bos, Tantek Çelik, Ian Hickson et al.. W3C.
[DOM]
DOM, Anne van Kesteren, Aryeh Gregor and Ms2ger. WHATWG.
[HTML]
HTML, Ian Hickson. WHATWG.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.

Acknowledgments

Many thanks to Robert O'Callahan for designing the initial model and being awesome.

Thanks to Chris Pearce, Darin Fisher, Edward O'Connor, fantasai, Giuseppe Pascale, Glenn Maynard, Ian Hickson, Ignacio Solla, João Eiras, Josh Soref, Matt Falkenhagen, Mihai Balan, Øyvind Stenhaug, Pat Ladd, Philip Jägenstedt, Rafał Chłodnicki, Rune Lillesveen, Sigbjørn Vik, Simon Pieters, Tab Atkins, and Vincent Scheib for also being awesome.