Copyright © 2019 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
The Screen Orientation API provides the ability to read the screen orientation type and angle, to be informed when the screen orientation changes, and to lock the screen to a specific orientation.
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/.
This document is a work in progress.
This document was published by the Web Platform Working Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification.
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 February 2018 W3C Process Document .
Screen
interface
The
CSSOM
View
Module
specification
defines
the
Screen
interface,
which
this
specification
extends:
partial interface Screen {
[SameObject] readonly attribute ScreenOrientation orientation;
};
orientation
attribute
The
orientation
attribute
is
an
instance
of
ScreenOrientation
.
ScreenOrientation
interface
[Exposed=Window]
interface ScreenOrientation : EventTarget {
Promise<void> lock(OrientationLockType orientation);
void unlock();
readonly attribute OrientationType type;
readonly attribute unsigned short angle;
attribute EventHandler onchange;
};
lock()
method
When
the
lock()
method
is
invoked,
the
user
agent
MUST
run
the
apply
an
orientation
lock
steps
to
the
responsible
document
using
orientation
.
unlock()
method
When
the
unlock()
method
is
invoked,
the
user
agent
MUST
run
the
steps
to
lock
the
orientation
of
the
responsible
document
to
the
responsible
document
's
default
orientation
.
unlock()
does
not
return
a
promise
because
it
is
equivalent
to
locking
to
the
default
orientation
which
might
or
might
not
be
known
by
the
user
agent
.
Hence,
the
user
agent
can
not
predict
what
the
new
orientation
is
going
to
be
and
even
if
it
is
going
to
change
at
all.
type
attribute
When
getting
the
type
attribute,
the
user
agent
MUST
return
the
responsible
document
's
current
orientation
type
.
angle
attribute
When
getting
the
angle
attribute,
the
user
agent
MUST
return
the
responsible
document
's
current
orientation
angle
.
angle
indicates
how
far
the
user
has
turned
the
device
counterclockwise
from
the
natural
orientation.
When
the
device
is
rotated
90°
counterclockwise,
the
screen
compensates
by
rotating
90°
clockwise,
so
angle
returns
90
.
If
the
device
is
rotated
90°
clockwise
from
its
natural
orientation,
the
screen
compensates
by
rotating
90°
counterclockwise,
so
angle
returns
270
.
The value returned by this property is always in the range 0-359. It never returns negative values.
onchange
attribute
The
onchange
attribute
is
an
event
handler
whose
corresponding
event
handler
event
type
is
"change"
.
OrientationType
enum
enum OrientationType {
"portrait-primary",
"portrait-secondary",
"landscape-primary",
"landscape-secondary"
};
OrientationLockType
enum
enum OrientationLockType {
"any",
"natural",
"landscape",
"portrait",
"portrait-primary",
"portrait-secondary",
"landscape-primary",
"landscape-secondary"
};
The
term
screen
is
equivalent
to
the
screen
of
the
output
device
associated
to
the
Window
,
as
per
[
CSSOM-VIEW
].
Algorithms
defined
in
this
specification
assume
that
for
each
document
there
is
a
pending
promise
,
which
is
initially
set
to
null
,
which
is
a
promise
whose
associated
operation
is
to
lock
the
screen
orientation.
All
documents
have
a
current
orientation
type
and
a
current
orientation
angle
.
Both
of
them
SHOULD
be
initialized
when
the
document
is
created,
otherwise
they
MUST
be
initialized
the
first
time
they
are
accessed
and
before
their
value
is
read.
The
user
agent
MUST
update
the
orientation
information
of
the
document
to
initialize
them.
For
a
given
document
,
the
current
orientation
type
and
the
current
orientation
angle
are
strongly
linked
in
the
sense
that
for
any
given
type,
there
will
be
a
specific
angle
associated.
One primary orientation will always be determined by the natural orientation of the device and this will then determine the secondary value of its related orientation.
For
example
a
device
held
in
its
natural
portrait
orientation
would
have
a
current
orientation
of
portrait-primary
and
its
portrait-secondary
orientation
would
be
its
position
when
rotated
180°.
The
user
agent
can
associate
the
other
*-primary
and
*-secondary
values
at
will.
For
example,
it
can
be
based
on
the
device
preferred
angles,
the
user's
preferred
orientations
or
the
current
orientation
when
the
application
starts.
The screen orientation values table presents the primary and secondary values that are determined by the device's natural orientation and the possibilities available to the user agent for setting the other primary and secondary orientation values.
| Natural Orientation | Primary Orientation 1 | Secondary Orientation 1 | Primary Orientation 2 | Secondary Orientation 2 |
|---|---|---|---|---|
| Portrait |
portrait-primary
Angle
0
|
portrait-secondary
Angle
180
|
landscape-primary
User agent to set at either
Angle
90
or
Angle
270
|
landscape-secondary
Set at the angle not used for landscape-primary |
| Landscape |
landscape-primary
Angle
0
|
landscape-secondary
Angle
180
|
portrait-primary
User agent to set at either
Angle
90
or
Angle
270
|
portrait-secondary
Set at the angle not used for portrait-primary |
Once
the
user
agent
has
set
the
primary
and
secondary
values
from
the
options
in
the
screen
orientation
values
table
,
the
current
orientation
type
and
the
current
orientation
angle
relation
MUST
be
kept
consistent
for
any
given
document
.
Never
assume
any
cross-devices
relationship
between
the
screen
orientation
type
and
the
screen
orientation
angle.
Any
assumption
would
be
wrong
given
that
a
device
might
have
90
and
270
as
the
angles
for
landscape
types
but
another
device
will
have
0
and
180
,
depending
on
its
natural
orientation.
Instead,
it
is
recommended
to
check
during
runtime
the
relationship
between
angle
and
type.
The
user
agent
MAY
require
a
document
and
its
associated
browsing
context
to
meet
one
or
more
security
conditions
in
order
to
be
able
to
lock
the
screen
orientation.
For
example,
a
user
agent
might
require
a
document
's
top-level
browsing
context
to
be
fullscreen
(see
Interaction
with
Fullscreen
API
)
in
order
to
allow
an
orientation
lock.
The user agent MAY reject all attempts to lock the screen orientation if the platform conventions do not expect applications to be able to change the screen orientation. For example, on most desktop platforms, applications can not change the screen orientation.
If
the
user
agent
supports
locking
the
screen
orientation,
it
MUST
allow
the
screen
to
be
locked
to
all
of
the
states
of
the
enum.
OrientationLockType
A
document
's
orientation
lock
is
the
orientation
lock
that
applies
on
its
top-level
browsing
context
.
An
orientation
lock
is
an
unordered
set
of
OrientationType
.
A
document
's
default
orientation
is
the
set
of
orientations
to
which
the
screen
orientation
is
locked
when
it
is
not
explicitly
locked
by
this
API
or
any
other
means.
For
the
perspective
of
a
document
,
locking
to
the
default
orientation
is
equivalent
to
unlocking
because
it
means
that
it
no
longer
has
a
lock
applied.
However,
it
does
not
mean
that
the
default
orientation
has
to
be
any
.
This section explains how this specification interacts with other related specifications of the platform.
As
a
security
condition
,
a
user
agent
MAY
restrict
locking
the
screen
orientation
exclusively
to
when
the
top-level
browsing
context
's
document
's
fullscreen
element
is
not
null.
When
that
security
condition
applies,
whenever
the
document
's
fullscreen
element
is
empty
and
a
screen
orientation
lock
is
applied,
the
user
agent
MUST
lock
the
orientation
of
the
document
to
the
document
's
default
orientation
.
This section is non-normative.
The
DeviceOrientation
specification
[
DEVICE-ORIENTATION
]
defines
a
deviceorientation
event
that
can
be
used
to
discover
the
physical
orientation
of
the
device.
Such
event
can
be
used
to
draw
things
on
the
screen
that
could
point
to
a
specific
direction.
A
basic
example
being
a
compass
application.
Another
example
would
be
an
application
giving
direction
to
the
user
or
an
augmented
reality
game
pointing
to
an
objective.
Drawing
on
the
screen
in
order
to
point
to
a
physical
location
requires
to
know
the
device
orientation
and
the
orientation
of
the
screen
in
the
device
coordinates.
Without
the
APIs
defined
in
this
specification,
a
developer
has
to
assume
that
the
document
's
current
orientation
angle
is
0
.
With
the
help
of
the
APIs
described
in
this
specification,
the
developer
can
apply
an
orientation
lock
to
a
document
using
natural
to
make
that
assumption
a
certitude.
Otherwise,
reading
the
document
's
current
orientation
angle
via
screen.orientation.angle
and
listening
to
the
"change"
event
can
help
the
developer
to
compensate
the
screen
orientation
angle.
This section is non-normative.
The
Web
Application
Manifest
specification
[
appmanifest
]
allows
web
applications
to
set
the
document
's
default
orientation
.
This section is non-normative.
The CSS Device Adaptation specification [ CSS-ADAPTATION ] defines, independently of this document, a way to lock the screen orientation for a web page using CSS.
This section is non-normative.
The Web Content Accessibility Guidelines 2.1 specification [ WCAG21 ] includes a Success Criterion ( SC 1.3.4 ) related to screen orientation.
The intent of this Success Criterion is to ensure that all essential content and functionality is available regardless of the display orientation (portrait or landscape). Some websites and applications automatically set the screen to a particular display orientation and expect that users will respond by rotating their device to match.
However, some users may have their devices mounted in a fixed orientation (e.g. on the arm of a power wheelchair). Therefore, websites and applications need to support both orientations by making sure essential content and functionality is available in each orientation. While the order of content and method of functionality may have differences the content and functionality must always be available. When a particular orientation is essential , the user needs to be advised of the orientation requirements.
This section is non-normative.
This example shows the current screen orientation to the console every time the screen orientation state changes.
<script> var show = function() { console.log("Orientation type is " + screen.orientation.type); console.log("Orientation angle is " + screen.orientation.angle);
}
screen.orientation.addEventListener("change", show);
window.onload = show;</script><button onclick='screen.orientation.unlock()'>
Unlock
</button><button onclick="screen.orientation.lock('portrait')">
Lock to portrait
</button><button onclick="screen.orientation.lock('landscape')">
Lock to landscape
</
button
>
This example waits to be fullscreen before locking the screen orientation and starting.
<script> var start = function() { document.onfullscreenchange = function() {
screen.orientation.lock('natural').then(startInternal);
}
document.documentElement.requestFullscreen();
}
</script><button onclick='start();'>
Start
</
button
>
This example asks the user to manually rotate the device if the Screen Orientation API is not available.
<script> var start = function() {
screen.orientation.lock('landscape-primary').then(
startInternal,
function() {
alert('To start, rotate your screen to landscape.');
var orientationChangeHandler = function() { if (!screen.orientation.type.startsWith('landscape')) { return;
}
screen.orientation.removeEventListener('change', orientationChangeHandler);
startInternal();
}
screen.orientation.addEventListener('change', orientationChangeHandler);
});
}
window.onload = start;
</
script
>
The
steps
to
update
the
orientation
information
of
a
document
are
as
follows:
document
's
current
orientation
type
to
landscape-primary
or
landscape-secondary
.
document
's
current
orientation
type
to
portrait-primary
or
portrait-secondary
.
document
's
current
orientation
angle
to
the
clockwise
angle
in
degrees
between
the
orientation
of
the
viewport
as
it
is
drawn
and
the
natural
orientation
of
the
device
(i.e.,
the
top
of
the
physical
screen).
This
is
the
opposite
of
the
physical
rotation.
In
other
words,
if
a
device
is
turned
90
degrees
on
the
right,
the
current
orientation
angle
would
be
270
degrees.
The
steps
to
apply
an
orientation
lock
to
a
document
using
orientation
are
as
follows:
DOMException
whose
name
is
NotSupportedError
and
abort
these
steps.
document
.
document
's
pending
promise
is
not
null
:
document
which
has
a
not
null
pending
promise
.
DOMException
whose
name
is
AbortError
.
null
.
document
's
active
sandboxing
flag
set
has
the
sandboxed
orientation
lock
browsing
context
flag
set,
or
user
agent
doesn't
meet
the
security
conditions
to
perform
an
orientation
change,
return
a
promise
rejected
with
a
DOMException
whose
name
is
SecurityError
and
abort
these
steps.
portrait-primary
or
portrait-secondary
or
landscape-primary
or
landscape-secondary
landscape
landscape-primary
,
or
landscape-secondary
,
or
both
to
orientations
.
portrait
portrait-primary
,
or
portrait-secondary
,
or
both
to
orientations
.
natural
portrait-primary
or
landscape-primary
to
orientations
such
as
the
associated
current
orientation
angle
is
0.
any
portrait-primary
,
portrait-secondary
,
landscape-primary
and
landscape-secondary
to
orientations
.
document
to
orientations
.
undefined
and
set
pending-promise
to
null
.
When
the
user
agent
has
to
lock
the
orientation
of
a
document
to
orientations
,
it
MUST
run
the
following
steps:
document
's
orientation
lock
to
orientations
.
document
's
orientation
lock
,
abort
these
steps.
document
's
current
orientation
type
will
be
equal
to
orientation
.
document
's
top-level
browsing
context
's
screen
orientation
from
changing
until
those
steps
are
run
again.
document
's
current
orientation
type
is
not
part
of
orientations
,
change
how
the
viewport
is
drawn
such
as
the
document
's
current
orientation
type
will
be
equal
to
one
of
orientations
'
values.
To determine the active orientation lock , the user agent MUST run the following steps:
document
that
is
visible
per
[
PAGE-VISIBILITY
],
the
active
orientation
lock
is
the
document
's
orientation
lock
.
document
that
is
visible
per
[
PAGE-VISIBILITY
]
but
only
one
of
those
document
s
is
focused,
the
active
orientation
lock
is
the
focused
document
's
orientation
lock
.
document
's
orientation
lock
,
unless
stated
otherwise
by
the
platform
conventions.
Whenever
the
active
orientation
lock
changes,
the
user
agent
MUST
run
the
steps
to
lock
the
orientation
of
the
document
to
the
document
's
orientation
lock
.
Whenever
a
top-level
browsing
context
is
navigated
,
the
user
agent
MUST
lock
the
orientation
of
the
document
to
the
document
's
default
orientation
.
Whenever the viewport's angle changes, the user agent MUST run the following steps as part of the next animation frame task :
document
.
null
:
undefined
.
null
.
lock
,
the
task
MUST
be
annotated
with
process
user
orientation
change
when
running
the
next
step.
change
at
doc
's
screen.orientation
object.
Whenever
a
document
becomes
visible
per
[
PAGE-VISIBILITY
],
in
other
words
after
the
now
visible
algorithm
is
run,
the
user
agent
MUST
run
the
following
substeps
as
part
of
the
next
animation
frame
task
:
document
's
current
orientation
type
and
current
orientation
angle
.
document
.
document
's
current
orientation
type
or
angle
from
the
document
's
current
orientation
angle
,
run
the
following
sub-steps:
document
's
pending
promise
is
not
null
:
document
's
pending
promise
with
undefined
.
document
's
pending
promise
to
null
.
lock
,
the
task
MUST
be
annotated
with
process
user
orientation
change
when
running
the
next
step.
change
at
the
document
's
screen.orientation
object.
An
algorithm
is
triggered
by
a
user
generated
orientation
change
if
the
task
in
which
the
algorithm
is
running
is
annotated
with
process
user
orientation
change
.
Developers
need
to
be
aware
that
a
screen.orientation
object
from
a
document
that
is
not
visible,
as
per
[
PAGE-VISIBILITY
],
will
not
receive
an
orientation
change
event.
This
is
to
prevent
unnecessary
changes
to
layout,
etc.
in
the
non-visible
web
application.
This section is non-normative.
The screen orientation type and angle of the device can be accessed with the API specified in this document, and can be a potential fingerprinting vector.
The screen orientation type can already be known by using the screen width and height. In practice, the additional information provided with the API concerning the angle of the device and the primary or secondary screen orientation is unlikely to be used by any competent attack.
The
following
concepts
and
interfaces
are
defined
in
[
HTML
]:
event
handler
,
event
handler
event
type
,
task
,
Window
,
Document
,
browsing
context
,
top-level
browsing
context
,
browsing
context's
active
document
,
navigated
browsing
context,
active
sandboxing
flag
set
,
sandboxed
orientation
lock
browsing
context
flag
,
responsible
document
,
list
of
the
descendant
browsing
contexts
.
The following is defined in [ FULLSCREEN ]: fullscreen element .
The following is defined in [ PAGE-VISIBILITY ]: now visible algorithm .
The following is defined in [ DOM ]: fire an event .
The following is used but not defined in [ FULLSCREEN ]: animation frame task .
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 , MUST , and SHOULD are to be interpreted as described in [ RFC2119 ].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Thanks to Marcos Cáceres, Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue, and Chaals McCathie Nevile for their useful comments.
Special thanks to Chris Jones and Jonas Sicking for their contributions to the initial design of this API.