Skip to content

Add can-lock-orientation CSS media feature #273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcoscaceres wants to merge 6 commits into
base: gh-pages
Choose a base branch
from
Open

Add can-lock-orientation CSS media feature #273

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
799be6d
Add can-lock-orientation CSS media feature
marcoscaceres Oct 17, 2025
b76a334
fixup mediaqueries-5 xref
marcoscaceres Oct 17, 2025
82353cc
fixup
marcoscaceres Oct 17, 2025
b4e9430
Fix use of boolean context
marcoscaceres Oct 28, 2025
3208037
fix markup
marcoscaceres Oct 28, 2025
45b5ee3
Merge branch 'gh-pages' into add-css-media-feature-206
marcoscaceres Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 139 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,14 @@
specification, exposes the current type and angle of the device's
screen orientation, and dispatches events when it changes. This enables
web applications to programmatically adapt the user experience for
multiple screen orientations, working alongside CSS. This API is
particularly useful for applications such as computer games, where
users physically rotate the device, but the screen orientation itself
should not change. The API restricts locking the screen orientation
only if certain [=pre-lock conditions=] are met.
multiple screen orientations, working alongside CSS.
The API restricts locking the screen orientation
only if certain [=pre-lock conditions=] are met.
This API particularly useful for applications such as
Copy link

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing word "is" before "particularly useful". Should be "This API is particularly useful for applications..."

Suggested change
This API particularly useful for applications such as
This API is particularly useful for applications such as

Copilot uses AI. Check for mistakes.
computer games, where users physically rotate the device, but the
screen orientation itself should not change. The specification also
defines CSS media features to enable feature detection of orientation
Copy link

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The text uses the plural "CSS media features" but only one media feature (can-lock-orientation) is being defined in this specification. Consider using the singular "CSS media feature" for accuracy, or if multiple features are planned, this is fine as is.

Suggested change
defines CSS media features to enable feature detection of orientation
defines a CSS media feature to enable feature detection of orientation

Copilot uses AI. Check for mistakes.
locking capabilities.
</p>
</section>
<section id="sotd">
Expand Down Expand Up @@ -903,6 +906,137 @@ <h2>
condition=].
</p>
</section>
<section data-cite="mediaqueries-5">
<h2>
CSS Integration
</h2>
<section>
<h2>
The `can-lock-orientation` media feature
</h2>
<p>
The <code><dfn>can-lock-orientation</dfn></code> media feature is
used to query whether the user agent supports locking the screen
orientation in the current context.
</p>
<p>
<strong>Value:</strong> <code>none</code> | <code>auto</code>
</p>
<p>
The <a>can-lock-orientation</a> media feature can be used to test
whether the user agent supports screen orientation locking
functionality.
</p>
Comment on lines +925 to +929
Copy link

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] These lines appear redundant with the initial description at lines 917-921. The description "The can-lock-orientation media feature can be used to test whether the user agent supports screen orientation locking functionality" repeats the same information as "used to query whether the user agent supports locking the screen orientation in the current context." Consider removing this paragraph to avoid redundancy.

Suggested change
<p>
The <a>can-lock-orientation</a> media feature can be used to test
whether the user agent supports screen orientation locking
functionality.
</p>

Copilot uses AI. Check for mistakes.
<dl>
<dt>
`none`
</dt>
<dd>
<p>
The user agent does not support screen orientation locking, or
locking is not possible in the current context. This includes
cases where:
</p>
<ul>
<li>The user agent does not implement the Screen Orientation API
</li>
<li>The document is not [=Document/fully active=]
Copy link

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The condition "The document is not [=Document/fully active=]" is less specific than the actual check performed by the API. According to the common safety checks (line 487-490), the API checks if the document is a "fully active descendant of a top-level traversable with user attention", not just "fully active". Consider updating this to match the actual API requirement to ensure consistency and accuracy.

Suggested change
<li>The document is not [=Document/fully active=]
<li>The document is not a [=Document/fully active=] descendant of a top-level traversable with user attention

Copilot uses AI. Check for mistakes.
</li>
<li>The document has the [=sandboxed orientation lock browsing
context flag=] set
</li>
<li>The document's [=Document/visibility state=] is "hidden"
</li>
<li>The current context doesn't meet the [=pre-lock conditions=]
</li>
</ul>
<p>
This keyword value evaluates as false in the [=boolean context=].
</p>
</dd>
<dt>
`auto`
</dt>
<dd>
The user agent supports screen orientation locking and locking is
possible in the current context, meaning a call to
{{ScreenOrientation/lock()}} could potentially succeed. This
keyword value evaluates as true in the [=boolean context=].
</dd>
</dl>
<p class="note">
The <a>can-lock-orientation</a> media feature evaluates to `auto`
when orientation locking functionality is available, but this doesn't
guarantee that a specific lock request will succeed. Factors such as
platform limitations or specific orientation support may still cause
{{ScreenOrientation/lock()}} to fail.
</p>
<div class="example">
<p>
The following example shows how to use the
<a>can-lock-orientation</a> media feature to conditionally display
orientation-related UI:
</p>
<pre class="css">
/* Hide rotation controls when orientation locking is not supported */
.rotation-controls {
display: none;
}

@media (can-lock-orientation) {
.rotation-controls {
display: block;
}
}
</pre>
<p>
In JavaScript, the media feature can be queried using:
</p>
<pre class="javascript">
if (window.matchMedia('(can-lock-orientation)').matches) {
// Orientation locking is potentially available
showOrientationControls();
} else {
// Orientation locking is not available
hideOrientationControls();
}
</pre>
</div>
<section>
<h2>
Privacy considerations for `can-lock-orientation`
</h2>
<p>
To prevent fingerprinting through user preferences or device
capabilities, user agents SHOULD consider the following privacy
mitigations:
</p>
<ul>
<li>When user preferences disable orientation locking, user agents
MAY still report `can-lock-orientation: auto` and only fail at the
time of actual {{ScreenOrientation/lock()}} invocation. This
prevents revealing user preference settings through CSS.
</li>
<li>In private browsing modes, user agents SHOULD normalize the
behavior to always report `can-lock-orientation: auto` for contexts
where the API would normally be available, regardless of user
preferences or detailed device capabilities.
</li>
<li>User agents SHOULD NOT use device-specific orientation support
capabilities (such as whether specific orientations are physically
possible) to determine the media feature value, as this could
reveal device characteristics.
</li>
</ul>
<p class="note">
These privacy considerations ensure that the
<a>can-lock-orientation</a> media feature provides useful
functionality for progressive enhancement while minimizing
potential fingerprinting vectors.
</p>
</section>
</section>
</section>
<section>
<h2>
Accessibility considerations
Expand Down