Copyright
©
2019
2020
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
).
W3C
liability
,
trademark
and
permissive
document
license
rules
apply.
This specification defines a means to programmatically determine the visibility state of a document. This can aid in the development of resource efficient web applications.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Page Visibility Level 2 replaces the first version of [ PAGE-VISIBILITY ] and includes:
VisibilityState.unloaded
has
been
removed.
Document.hidden
is
historical.
Use
Document.visibilityState
instead.
Document.onvisibilitychange
has
been
added.
This document was published by the Web Performance Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-web-perf@w3.org ( archives ).
Please see the Working Group's implementation report .
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 March 2019 W3C Process Document .
This section is non-normative.
The
Page
Visibility
API
defines
a
means
to
programmatically
determine
the
visibility
state
of
the
a
top-level
browsing
context
,
context,
and
to
be
notified
if
the
visibility
state
changes.
Without
knowing
the
visibility
state
of
a
page,
web
developers
have
been
designing
web
pages
as
if
they
are
always
visible
.
This
not
only
results
in
higher
machine
resource
utilization,
but
it
prevents
web
developers
from
making
runtime
decisions
based
on
whether
the
web
page
is
visible
to
the
user.
Designing
web
pages
with
knowledge
of
the
page's
document's
visibility
state
can
result
in
improved
user
experiences
and
power
efficient
sites.
With this API, web applications can choose to alter their behavior based on whether they are visible to the user or not. For example, this API can be used to scale back work when the page is no longer visible .
This section is non-normative.
To
improve
the
user
experience
and
optimize
CPU
and
power
efficiency
the
application
could
autoplay
a
video
when
the
application
is
visible
,
and
automatically
pause
the
playback
when
the
application
is
hidden
:
const videoElement = document.getElementById("videoElement");
// Autoplay the video if application is visible
if (document.visibilityState === "visible") {
videoElement.play();
}
// Handle page visibility change events
function handleVisibilityChange() {
if (document.visibilityState === "hidden") {
videoElement.pause();
} else {
videoElement.play();
}
}
document
.addEventListener(
'visibilitychange'
,
handleVisibilityChange);
Similar
logic
can
be
applied
to
intelligently
pause
and
resume,
or
throttle,
execution
of
application
code
such
as
animation
loops,
analytics,
and
other
types
of
processing.
By
combining
the
attribute
of
the
visibilityState
Document
interface
and
the
visibilitychange
event,
the
application
is
able
to
both
query
and
listen
to
page
visibility
events
to
deliver
a
better
user
experience,
as
well
as
improve
efficiency
and
performance
of
its
execution.
The
Document
of
the
top-level
browsing
context
can
be
in
one
of
the
following
visibility
states
:
Document
is
not
visible
at
all
on
any
screen.
Document
is
at
least
partially
visible
on
at
least
one
screen.
The
visibility
states
are
reflected
in
the
API
via
the
enum.
VisibilityState
VisibilityState
enum
WebIDLenumVisibilityState{ "hidden", "visible" };
The
VisibilityState
enum
is
used
to
represent
the
visibility
states
.
The
"
hidden
"
enum
value
represents
the
hidden
visibility
state
.
Likewise,
the
"
visible
"
enum
value
represents
the
visible
visibility
state
.
Document
interface
This
specification
extends
the
Document
interface:
WebIDLpartial interface Document { readonly attributeVisibilityStatevisibilityState; attribute EventHandleronvisibilitychange; };
visibilityState
attribute
On
getting,
the
attribute
the
user
agent
MUST
run
the
steps
to
determine
the
visibility
state
:
visibilityState
VisibilityState
value
that
best
matches
the
visibility
state
of
doc
:
To
accommodate
assistive
technologies
that
are
typically
full
screen
but
still
show
a
view
of
the
page,
when
applicable,
on
getting,
the
attribute
MAY
return
"
visibilityState
visible
"
,
",
instead
of
"
hidden
"
,
",
when
the
user
agent
is
not
minimized
but
is
fully
obscured
by
other
applications.
Examples
of
ways
that
"
"
may
be
returned:
hidden
onvisibilitychange
event
handler
attribute
The
onvisibilitychange
attribute
is
an
event
handler
IDL
attribute
for
the
visibilitychange
event
type.
visibilitychange
changes
The task source for these tasks is the user interaction task source .
When
the
user
agent
determines
that
the
visibility
of
the
Document
of
the
top-level
browsing
context
has
changed,
the
user
agent
MUST
run
the
following
steps:
Document
of
the
top-level
browsing
context
.
Document
The now visible algorithm runs the following steps synchronously:
Document
of
the
top-level
browsing
context
.
visibilitychange
"
that
bubbles,
isn't
cancelable,
and
has
no
default
action,
at
the
doc
.
The now hidden algorithm runs the following steps synchronously:
Document
of
the
top-level
browsing
context
.
visibilitychange
"
that
bubbles,
isn't
cancelable,
and
has
no
default
action,
at
the
doc
.
The
Page
Visibility
API
enables
developers
to
know
when
a
Document
is
visible
or
in
focus.
Existing
mechanisms,
such
as
the
focus
and
blur
events,
when
attached
to
the
Window
object
already
provide
a
mechanism
to
detect
when
the
Document
is
the
active
document;
the
unload
event
provides
a
notification
that
the
page
is
being
unloaded.
The following concepts and interfaces are defined in the [ HTML ] specification:
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
onvisibilitychange
attribute
for
Document
§5.3
visibilitychange
§6.
visibilityState
attribute
for
Document
§5.2
VisibilityState
enum
§4.
Document
interface
Window
)
Document
)
EventHandler
Window
)
Document
)
Window
)
Window
)
Window
interface
boolean
type
Thanks to Alex Komoroske, Arvind Jain, Boris Zbarsky, Cameron McCormack, James Robinson, Jason Weber, Jonas Sicking, Karen Anderson, Kyle Simpson, Nat Duca, Nic Jansma, Philippe Le Hegaret, and Todd Reifsteck for their contributions to this work.