Editorial review: Add docs for the viewport segments api #40528

chrisdavidmills · 2025-07-25T11:36:14Z

Description

Chrome 138 adds the Viewport Segments API, which provides a way to access the position and dimensions of logically separate viewport regions. Viewport segments are created when the viewport is split by one or more hardware features (such as a fold or a hinge between separate displays).

The API is made up of several related features:

The Viewport interface and segments property.
Viewport segment media features.
Viewport segment environment variables.

See also the related ChromeStatus entry: https://chromestatus.com/feature/5170498990243840

This PR adds docs for these new features. Specifically, it:

Adds a Viewport segments API landing page and "Using..." guide
Adds an API reference for Viewport and Window.viewport.
Adds the new media features to the media queries module page and @media landing page.
Adds information about the new environment variables to the env() page, and generally cleans up the structure of the page a bit.

Motivation

Additional details

Related issues and pull requests

…ntent into viewport-segments-api

github-actions · 2025-07-25T11:52:31Z

Preview URLs (13 pages)

Flaws (11)

Note! 7 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Viewport_segments_API
Title: Viewport Segments API
Flaw count: 2

broken_links:
- Can't resolve /en-US/docs/Web/API/Viewport_API
unknown:
- Invalid slug for templ/sidebar: Viewport segments API

URL: /en-US/docs/Web/API/Viewport_segments_API/Using
Title: Using the Viewport Segments API
Flaw count: 1

unknown:
- Invalid slug for templ/sidebar: Viewport segments API

URL: /en-US/docs/Web/API/Window
Title: Window
Flaw count: 2

macros:
- Macro produces link /en-US/docs/Web/API/HTMLElement/invalid_event which is a redirect
- Macro produces link /en-US/docs/Web/API/Element/select_event which is a redirect

URL: /en-US/docs/Web/API/Window/viewport
Title: Window: viewport property
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/Web/API/Viewport_API

URL: /en-US/docs/Web/CSS/@media
Title: @media
Flaw count: 2

broken_links:
- Can't resolve /en-US/docs/Web/CSS/media-query-list
- Can't resolve /en-US/docs/Web/CSS/rule-list

URL: /en-US/docs/Web/CSS/env
Title: env()
Flaw count: 3

broken_links:
- Can't resolve /en-US/docs/Web/CSS/declaration-value
unknown:
- Error serializing baseline for numeric-seperators: missing field description``
- Error serializing baseline for single-color-gradients: missing field description``

External URLs (12)

URL: /en-US/docs/Web/API/Viewport
Title: Viewport

https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Viewport_segments_API
Title: Viewport Segments API

https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/viewport-segment-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Viewport_segments_API/Using
Title: Using the Viewport Segments API

https://creativecommons.org/licenses/by/4.0/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/viewport-segment-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Viewport/segments
Title: Viewport: segments property

https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/@media/horizontal-viewport-segments
Title: horizontal-viewport-segments

https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/viewport-segment-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/@media/vertical-viewport-segments
Title: vertical-viewport-segments

https://developer.chrome.com/blog/foldable-apis-ot (1 time) (Note! This may be a new URL 👀)
https://mdn.github.io/dom-examples/viewport-segment-api/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/env
Title: env()

https://mdn.github.io/dom-examples/viewport-segment-api/ (2 times) (Note! This may be a new URL 👀)

(comment last updated: 2025-09-18 09:53:27)

chrisdavidmills · 2025-07-25T11:55:29Z

Hi @darktears! This PR contains the viewport segments API docs to accompany the demo you reviewed earlier in the week.

Would you be OK to provide a technical review of these, too? It isn't super-urgent; I'm on vacation next week anyway, so you've got plenty of time.

files/en-us/web/css/@media/horizontal-viewport-segments copy/index.md

files/en-us/web/css/@media/horizontal-viewport-segments/index.md

files/en-us/web/css/env/index.md

chrisdavidmills · 2025-08-05T10:14:58Z

Thanks a lot for the review, @darktears; let me know if you have any other comments or concerns.

estelle

rereview of env().

please don't hate me.

files/en-us/web/css/env/index.md

estelle

env() page again.

files/en-us/web/css/env/index.md

estelle

didn't finish.

did create a module landing page for viewport mod - #41070 assume that should go live when this does

files/en-us/web/css/css_environment_variables/index.md

files/en-us/web/api/window/index.md

files/en-us/web/api/viewport/index.md

files/en-us/web/css/@media/vertical-viewport-segments/index.md

Co-authored-by: Estelle Weyl <[email protected]>

files/en-us/web/css/css_environment_variables/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

estelle

A few comments to go with the PR chrisdavidmills#13

estelle · 2025-09-16T10:09:49Z

files/en-us/web/api/viewport/index.md

+
+## Instance properties
+
+_Inherits properties from its parent, {{DOMxRef("EventTarget")}}._


Is this accurate?
I am not seeing anything about {{DOMxRef("EventTarget")}} being the parent. I thought Window was the parent.

I suspect this was a copy and paste error. I'll fix it.

estelle · 2025-09-16T12:34:00Z

files/en-us/web/api/viewport_segments_api/using/index.md

+The {{cssxref("@media/horizontal-viewport-segments")}} media feature detects whether the device has a specified number of viewport segments laid out horizontally, whereas the {{cssxref("@media/vertical-viewport-segments")}} media feature detects whether the device has a specified number of viewport segments laid out vertically.
+
+> [!NOTE]
+> Current implementations do not support more than two foldable screens.


Where does this information come from? bug / ticket #?

@darktears, the engineer who implemented this stuff, told me this.

estelle · 2025-09-16T13:57:39Z

files/en-us/web/api/viewport_segments_api/using/index.md

+}
+```
+
+Here, we are setting the outer wrapper to have a horizontal flexbox layout when the viewport segments are laid out horizontally. We then set the left container to have a width equal to the left segment width, and the right container to have a width equal to the right segment width. To calculate how much width the fold takes up in between the two, we subtract the left edge offset of the right container from the right edge offset of the left container.


this is identical to below. I wrote a grid example to replace this section

estelle · 2025-09-16T14:35:59Z

files/en-us/web/api/viewport_segments_api/using/index.md

+## Example walkthrough
+
+Let's look at these features in action in a real example. You can see our example running live at [Viewport segment API demo](https://mdn.github.io/dom-examples/viewport-segment-api/) (see the full [source code](https://github.com/mdn/dom-examples/tree/main/viewport-segment-api) also). If possible, you should view this on a foldable device. Current browser developer tools enable emulating foldable devices, but don't include emulation of the different physical segments.
+


Adding an attribution

estelle · 2025-09-16T15:02:08Z

files/en-us/web/api/window/viewport/index.md

+
+The `viewport` read-only property of the {{domxref("Window")}} interface returns a {{domxref("Viewport")}} object instance, which provides information about the current state of the device's viewport.
+
+This property can be considered the entry point to the [Viewport segments API](/en-US/docs/Web/API/Viewport_segments_API), which relies on viewport segment information returned by the {{domxref("Viewport.segments")}} property.


switched this to be more like other web-api-instance-property that are just placeholders for the same slug but without the /window/

estelle · 2025-09-16T15:02:44Z

files/en-us/web/api/window/viewport/index.md

+
+### Basic `viewport` usage
+
+This snippet will loop through each segment in the viewport, and log a string to the console detailing the index number, width, and height.


see comment above

Viewport-segments: Remote edits to PR

estelle

Yay! Just one note to remove (or add a link to bug so we can track for removal at a later time)

files/en-us/web/api/viewport_segments_api/using/index.md

Co-authored-by: Estelle Weyl <[email protected]>

Add docs for the viewport segments api

ea6ac48

chrisdavidmills requested review from a team as code owners July 25, 2025 11:36

chrisdavidmills requested review from estelle, sideshowbarker and pepelsbey and removed request for a team July 25, 2025 11:36

github-actions bot added Content:CSS Cascading Style Sheets docs Content:WebAPI Web API docs labels Jul 25, 2025

chrisdavidmills changed the title ~~Add docs for the viewport segments api~~ Technical review: Add docs for the viewport segments api Jul 25, 2025

github-actions bot added the size/l [PR only] 501-1000 LoC changed label Jul 25, 2025

chrisdavidmills added 3 commits July 25, 2025 12:44

Merge branch 'main' into viewport-segments-api

b559269

rename wrongly-named directory

1e56e76

Merge branch 'viewport-segments-api' of github.com:chrisdavidmills/co…

bbf33cf

…ntent into viewport-segments-api

sideshowbarker removed their request for review July 26, 2025 00:43

estelle removed their request for review July 31, 2025 12:15

github-actions bot added the merge conflicts 🚧 [PR only] label Aug 4, 2025

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into viewport-segments-api

f93fa22

github-actions bot removed the merge conflicts 🚧 [PR only] label Aug 4, 2025

darktears reviewed Aug 4, 2025

View reviewed changes

chrisdavidmills added 2 commits August 5, 2025 10:27

Merge branch 'main' into viewport-segments-api

8d158ae

Fixes for darktears review comments

07afeac

chrisdavidmills requested a review from darktears August 5, 2025 10:14

Fixes for estelle review comments

d68c717

chrisdavidmills requested a review from estelle September 1, 2025 11:17

estelle reviewed Sep 4, 2025

View reviewed changes

Fixes for estelle review comments

fb04f87

chrisdavidmills requested a review from estelle September 4, 2025 12:33

estelle reviewed Sep 8, 2025

View reviewed changes

estelle mentioned this pull request Sep 9, 2025

CSS module: viewport #41070

Merged

estelle reviewed Sep 9, 2025

View reviewed changes

chrisdavidmills and others added 3 commits September 9, 2025 09:55

Update files/en-us/web/css/env/index.md

bc9a072

Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/env/index.md

0b65c26

Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/css_environment_variables/index.md

1a1371d

Co-authored-by: Estelle Weyl <[email protected]>

github-actions bot reviewed Sep 9, 2025

View reviewed changes

files/en-us/web/css/css_environment_variables/index.md Outdated Show resolved Hide resolved

chrisdavidmills and others added 3 commits September 9, 2025 09:59

Update files/en-us/web/css/css_environment_variables/index.md

32ba8bb

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Merge branch 'main' into viewport-segments-api

3a2461d

Fixes for estelle review comments

348ffa9

chrisdavidmills requested a review from estelle September 9, 2025 09:54

chrisdavidmills and others added 4 commits September 9, 2025 15:00

Small wording upddate

32ac90e

Merge branch 'main' into viewport-segments-api

81ed4fb

remote edits to PR

aa7a694

groupdata capitalization

d7f14d3

estelle reviewed Sep 16, 2025

View reviewed changes

chrisdavidmills added 4 commits September 17, 2025 15:38

Merge pull request #13 from mdn/segments

b348abd

Viewport-segments: Remote edits to PR

Remove incorrect inheritance claim

4a83e58

Edit grammar

36b3b8a

grammar fixes, fill in missing URLs

2134dbe

chrisdavidmills requested a review from estelle September 17, 2025 15:07

estelle approved these changes Sep 18, 2025

View reviewed changes

files/en-us/web/api/viewport_segments_api/using/index.md Outdated Show resolved Hide resolved

Update files/en-us/web/api/viewport_segments_api/using/index.md

dd943db

Co-authored-by: Estelle Weyl <[email protected]>

chrisdavidmills merged commit 7860297 into mdn:main Sep 18, 2025
9 checks passed

chrisdavidmills deleted the viewport-segments-api branch September 18, 2025 10:01


		## Instance properties

		_Inherits properties from its parent, {{DOMxRef("EventTarget")}}._

		## Example walkthrough

		Let's look at these features in action in a real example. You can see our example running live at [Viewport segment API demo](https://mdn.github.io/dom-examples/viewport-segment-api/) (see the full [source code](https://github.com/mdn/dom-examples/tree/main/viewport-segment-api) also). If possible, you should view this on a foldable device. Current browser developer tools enable emulating foldable devices, but don't include emulation of the different physical segments.


		The `viewport` read-only property of the {{domxref("Window")}} interface returns a {{domxref("Viewport")}} object instance, which provides information about the current state of the device's viewport.

		This property can be considered the entry point to the [Viewport segments API](/en-US/docs/Web/API/Viewport_segments_API), which relies on viewport segment information returned by the {{domxref("Viewport.segments")}} property.


		### Basic `viewport` usage

		This snippet will loop through each segment in the viewport, and log a string to the console detailing the index number, width, and height.

Editorial review: Add docs for the viewport segments api #40528

Editorial review: Add docs for the viewport segments api #40528

Uh oh!

Conversation

chrisdavidmills commented Jul 25, 2025

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisdavidmills commented Jul 25, 2025

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills commented Aug 5, 2025

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

github-actions bot commented Jul 25, 2025 •

edited

Loading