Update wording around multi-keyword syntax for the `display` property #42986

romainmenke · 2026-02-01T15:41:21Z

Description

The current docs for display warn slightly against using the multi-keyword syntax and have some incorrect content (e.g. block is not a precomposed value, only inline-block is).

Motivation

Given that multi-keyword syntax is now Baseline Widely Available it seems a good time to update the wording to promote this syntax a bit more.

The multi-keyword syntax makes it easier to fully understand how both inner and outer display modes function.

Additional details

https://drafts.csswg.org/css-display-3/#the-display-properties

Related issues and pull requests

None

files/en-us/web/css/reference/properties/display/index.md

github-actions · 2026-02-01T15:42:51Z

Preview URLs (1 page)

/en-US/docs/Web/CSS/Reference/Properties/display

Flaws (4)

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/CSS/Reference/Properties/display
Title: display
Flaw count: 4

macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

(comment last updated: 2026-02-03 07:31:17)

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

files/en-us/web/css/reference/properties/display/index.md

estelle

Thank you for suggesting these edits. We do need to update this page. I made several suggestions.

estelle · 2026-02-02T22:11:32Z

files/en-us/web/css/reference/properties/display/index.md

-display: contents;
+display: table;

 /* multi-keyword syntax */


we should either use "short syntax" and "full syntax" OR "single-keyword" and "multi-keyword".

display: inline list-item is both "short syntax" and "multi-keyword".

As the values are broken down by data-type under values, I suggest we keep it to three headers in the syntax section:

short display

full display

global values

I've applied this suggestion, please let me know if I misunderstood or if further changes are needed.

moved precomposed values into short display

moved none and contents into short display (as seen in the table here)

omitted table-row from this section, it doesn't fit in any of these three sections

estelle · 2026-02-02T22:38:45Z

files/en-us/web/css/reference/properties/display/index.md


 > [!NOTE]
-> When browsers that support multi-keyword syntax encounter a display property that only has an **outer** value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).
+> When browsers encounter a display property that only has an **outer** value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).


is this true?

let styleMap = el.computedStyleMap(); styleMap.get("display").value /* returns outer without inner */

I think it may be more accurate to write:

Suggested change

> When browsers encounter a display property that only has an **outer** value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).

When a display property has only an **outer** value set (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).

I agree! Good catch

I've applied a slight variant of your suggestions. Please let me know if this doesn't cover your feedback.

files/en-us/web/css/reference/properties/display/index.md

estelle · 2026-02-02T22:45:55Z

files/en-us/web/css/reference/properties/display/index.md


 > [!NOTE]
-> When browsers that support multi-keyword syntax encounter a display property that only has an **inner** value (e.g., `display: flex` or `display: grid`), the outer value is set to `block` (e.g., `display: block flex` and `display: block grid`).
+> When browsers encounter a display property that only has an **inner** value (e.g., `display: flex` or `display: grid`), the outer value is set to `block` (e.g., `display: block flex` and `display: block grid`).


same comment as above. it defaults, but it isn't set (as in, there is no effect if querying the display value)

files/en-us/web/css/reference/properties/display/index.md

Co-authored-by: Estelle Weyl <estelle@openwebdocs.org>

romainmenke · 2026-02-03T07:09:22Z

files/en-us/web/css/reference/properties/display/index.md


 > [!NOTE]
-> When browsers that support multi-keyword syntax encounter a display property that only has an **outer** value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).
+> When a display property has only an **outer** value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).


Suggested change

> When a display property has only an **outer** value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).

> When a display property is specified with only an **outer** value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).

When a display property is specified with only an **outer** value

vs.

When a display property has only an **outer** value set as suggested by @estelle

value set could be read as a set of values, which was confusing to me.

This wording matches: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Display/Multi-keyword_syntax#:~:text=%22If%20a%20%3Cdisplay%2Doutside%3E%20value%20is%20specified%20but%20%3Cdisplay%2Dinside%3E%20is%20omitted%2C%20the%20element's%20inner%20display%20type%20defaults%20to%20flow.%22

files/en-us/web/css/reference/properties/display/index.md

romainmenke · 2026-02-03T07:25:11Z

Thank you for the review @estelle 🙇
This is ready for a second look

estelle

Thanks! 🎉

Update wording around multi-keyword syntax for the display property

c18661a

romainmenke requested a review from a team as a code owner February 1, 2026 15:41

romainmenke requested review from estelle and removed request for a team February 1, 2026 15:41

github-actions bot added Content:CSS Cascading Style Sheets docs size/s [PR only] 6-50 LoC changed labels Feb 1, 2026

github-actions bot reviewed Feb 1, 2026

View reviewed changes

files/en-us/web/css/reference/properties/display/index.md Outdated Show resolved Hide resolved

romainmenke and others added 2 commits February 1, 2026 16:43

Apply suggestion from @github-actions[bot]

1bc2dab

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

Update index.md

acb23af

romainmenke commented Feb 1, 2026

View reviewed changes

files/en-us/web/css/reference/properties/display/index.md Outdated Show resolved Hide resolved

Update files/en-us/web/css/reference/properties/display/index.md

dd1cb91

estelle reviewed Feb 2, 2026

View reviewed changes

romainmenke commented Feb 3, 2026

View reviewed changes

files/en-us/web/css/reference/properties/display/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

a511b6f

Co-authored-by: Estelle Weyl <estelle@openwebdocs.org>

romainmenke commented Feb 3, 2026

View reviewed changes

romainmenke added 3 commits February 3, 2026 08:11

Apply suggestions from code review

fb3e762

Update index.md

3947248

Merge branch 'main' into patch-1

09c8968

set -> specified

6d31a4b

estelle approved these changes Feb 3, 2026

View reviewed changes

estelle merged commit 3b50e6c into mdn:main Feb 3, 2026
7 checks passed

	> When browsers encounter a display property that only has an outer value (e.g., `display: block` or `display: inline`), the inner value is set to `flow` (e.g., `display: block flow` and `display: inline flow`).
	When a display property has only an outer value set (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).

	> When a display property has only an outer value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).
	> When a display property is specified with only an outer value (e.g., `display: block` or `display: inline`), the inner value defaults to `flow` (e.g., `display: block flow` and `display: inline flow`).

Update wording around multi-keyword syntax for the display property #42986

Update wording around multi-keyword syntax for the display property #42986

Conversation

romainmenke commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

Uh oh!

github-actions bot commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

estelle Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

romainmenke Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

estelle Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

romainmenke Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

romainmenke Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

estelle Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

romainmenke Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

romainmenke commented Feb 3, 2026

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Update wording around multi-keyword syntax for the `display` property #42986

Update wording around multi-keyword syntax for the `display` property #42986

romainmenke commented Feb 1, 2026 •

edited

Loading

github-actions bot commented Feb 1, 2026 •

edited

Loading

romainmenke Feb 3, 2026 •

edited

Loading