-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
1202 lines (1007 loc) · 49.7 KB
/
Overview.bs
File metadata and controls
1202 lines (1007 loc) · 49.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: CSS Display Module Level 3
Status: ED
Work Status: Refining
ED: https://drafts.csswg.org/css-display/
Shortname: css-display
Group: csswg
Level: 3
TR: https://www.w3.org/TR/css-display-3/
Previous Version: https://www.w3.org/TR/2017/WD-css-display-3-20170720/
Previous Version: https://www.w3.org/TR/2017/WD-css-display-3-20170126/
Previous Version: https://www.w3.org/TR/2015/WD-css-display-3-20151015/
Previous Version: https://www.w3.org/TR/2015/WD-css-display-3-20150721/
Previous Version: https://www.w3.org/TR/2014/WD-css-display-3-20140911/
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Abstract: This module describes how the CSS formatting box tree is generated from the document element tree and defines the 'display' property that controls it.
Ignored Terms: display-model, display-role, table row group box, absolutely positioned, table formatting context
At Risk: Application of ''::first-letter'' in the presence of run-ins
At Risk: ''display: run-in''
At Risk: All multi-keyword values of 'display' and ''display: inline list-item''
</pre>
<pre class="link-defaults">
spec:css-break-3; type:dfn; text:fragment;
spec:css22;
type:property; text:overflow;
type:dfn;
text: table wrapper box
text: table box
spec: html; type: dfn; text: rendered legend
spec:css-pseudo-4; type:selector;
text: ::first-letter
text: ::first-line
text: ::before
text: ::after
</pre>
<h2 id="intro">
Introduction</h2>
<p><em>This section is normative.</em>
CSS takes a source document, organized as a <dfn export for=CSS lt="element tree">tree</dfn> of <dfn export for=CSS lt="element">elements</dfn> and <dfn export for=CSS lt="text node">text nodes</dfn>,
and renders it onto a <a href="https://www.w3.org/TR/CSS2/intro.html#canvas">canvas</a> (such as your screen, a piece of paper, or an audio stream).
To do this, it generates an intermediary structure,
the <dfn export for=CSS>box tree</dfn>,
which represents the formatting structure of the rendered document.
Each <dfn export for=CSS>box</dfn> in the <a>box tree</a>
represents its corresponding <a>element</a> (or <a>pseudo-element</a>)
in space and/or time on the canvas,
while each <dfn export for=CSS>text run</dfn> in the <a>box tree</a>
likewise represents the contents of its corresponding <a>text nodes</a>.
To create the <a>box tree</a>,
CSS first uses <a href="https://www.w3.org/TR/css-cascade/">cascading and inheritance</a>,
to assign a <a>computed value</a> for each CSS property
to each <a>element</a> and <a>text node</a> in the source tree.
(See [[!CSS3-CASCADE]].)
Then, for each <a>element</a>,
CSS generates zero or more <a>boxes</a>
as specified by that element's 'display' property.
Typically, an element generates a single <a>box</a>.
However, some 'display' values
(e.g. ''display: list-item'')
generate more than one box
(e.g. a <a href="https://www.w3.org/TR/CSS2/visuren.html#principal-box">principal block box</a> and a <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>).
And some values
(such as ''display/none'' or ''display/contents'')
cause the <a>element</a> and/or its descendants to not generate any <a>boxes</a> at all.
<a>Boxes</a> are assigned the same styles as their generating <a>element</a>, unless otherwise indicated.
They're often referred to by their 'display' type--
e.g. a <a>box</a> generated by an element with ''display: block'' is called a “block box” or just a “block”.
Similarly, each contiguous sequence of sibling <a>text nodes</a> generates a <a>text run</a>,
which is assigned the same styles as the generating <a>text nodes</a>.
An <dfn for=CSS lt="anonymous|anonymous box" export>anonymous box</dfn> is is a box that is not associated with any element.
<a>Anonymous boxes</a> are generated in certain circumstances
to fix up the <a>box tree</a> when it requires a particular nested structure
that is not provided by the boxes generated from the <a>element tree</a>.
For example, a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table cell box</a>
requires a particular type of parent box (the <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>),
and will generate an <a>anonymous</a> <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a> around itself
if its parent is not a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>.
(See [[CSS2]] § <a href="https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes">17.2.1</a>.)
Unlike element-generated boxes, whose styles inherit strictly through the element tree,
anonymous boxes (which only exist in the <a>box tree</a>)
<a href="https://www.w3.org/TR/css-cascade/#inheriting">inherit</a> through their <a>box tree</a> parentage.
In the course of layout,
<a>boxes</a> and <a>text runs</a> can be broken into multiple <a>fragments</a>.
This happens, for example, when an inline box and/or text run is broken across lines,
or when a block box is broken across pages or columns.
A <a>box</a> therefore consists of one or more <a>box fragments</a>,
and a <a>text run</a> consists of one or more <a lt=fragment>text fragments</a>.
See [[CSS3-BREAK]] for more information on <a>fragmentation</a>.
Note: Many of the CSS specs were written before this terminology was ironed out,
or refer to things incorrectly,
so view older specs with caution when they're using these terms.
It should be possible to infer from context which term they really mean.
Please <a href="#status">report errors</a> in specs when you find them,
so they can be corrected.
Note: Further information on the “aural” box tree
and its interaction with the 'display' property
can be found in the <a href="https://www.w3.org/TR/css3-speech/#aural-model">CSS Speech Module</a>.
[[!CSS3-SPEECH]]
<h3 id="placement">
Module interactions</h3>
This module replaces and extends the definition of the 'display' property defined in [[!CSS2]] section 9.2.4.
None of the properties in this module apply to the <code>::first-line</code> or <code>::first-letter</code> pseudo-elements.
<h3 id="values">
Values</h3>
This specification follows the <a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]].
Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
Other CSS modules may expand the definitions of these value types.
In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the <a>CSS-wide keywords</a> keywords as their property value.
For readability they have not been repeated explicitly.
<h2 id='the-display-properties'>
Box Layout Modes: the 'display' property</h2>
<pre class="propdef">
Name: display
Value: [ <<display-outside>> || <<display-inside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>
Initial: inline
Applies to: all elements
Inherited: no
Computed value: as specified
Animatable: no
Media: all
</pre>
The 'display' property defines an element's <dfn export>display type</dfn>,
which consists of the two basic qualities of how an element generates boxes:
* the <dfn export local-lt="inner">inner display type</dfn>,
which defines (if it is a <a lt="replaced element">non-replaced element</a>) the kind of <a>formatting context</a> it generates,
dictating how its descendant boxes are laid out.
(The inner display of a <a>replaced element</a> is outside the scope of CSS.)
* the <dfn export local-lt="outer">outer display type</dfn>,
which dictates how the box itself participates in <a>flow layout</a>.
<a>Text runs</a> have no <a>display type</a>.
Some 'display' values have additional side-effects:
such as ''list-item'', which also generates a ''::marker'' pseudo-element,
and ''display/none'', which causes the element's entire subtree to be left out of the box tree.
Values are defined as follows:
<pre class='prod'>
<dfn><display-outside></dfn> = block | inline | run-in ;
<dfn><display-inside></dfn> = flow | flow-root | table | flex | grid | ruby ;
<dfn><display-listitem></dfn> = list-item && <<display-outside>>? && [ flow | flow-root ]? ;
<dfn><display-internal></dfn> = table-row-group | table-header-group |
table-footer-group | table-row | table-cell |
table-column-group | table-column | table-caption |
ruby-base | ruby-text | ruby-base-container |
ruby-text-container ;
<dfn><display-box></dfn> = contents | none ;
<dfn><display-legacy></dfn> = inline-block | inline-table | inline-flex | inline-grid ;
</pre>
The following informative table summarizes the values of 'display':
<style>
#display-value-summary td,
#display-value-summary th { text-align: left; }
</style>
<table class='data' id="display-value-summary">
<thead>
<tr>
<th>Short 'display'
<th>Full 'display'
<th>Generated box
<tbody title="Box Suppression Display Types">
<tr>
<td>''display/none''
<td>—
<td>subtree omitted from <a>box tree</a>
<tr>
<td>''display/contents''
<td>—
<td>element replaced by contents in <a>box tree</a>
<tbody title="Flow Layout Display Types">
<tr>
<td>''block''
<td>''block flow''
<td><a>block-level</a> <a>block container</a>
<abbr title="also known as">aka</abbr> <a>block box</a>
<tr>
<td>''flow-root''
<td>''block flow-root''
<td><a>block-level</a> <a>block container</a>
that establishes a new <a>block formatting context</a> (<a>BFC</a>)
<tr>
<td>''inline''
<td>''inline flow''
<td><a>inline box</a>
<tr>
<td>''inline-block''
<td>''inline flow-root''
<td><a>inline-level</a> <a>block container</a>
<tr>
<td>''run-in''
<td>''run-in flow''
<td><a>run-in box</a> (<a>inline box</a> with special box-tree-munging rules)
<tr>
<td>''list-item''
<td>''list-item block flow''
<td><a>block box</a>
with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>
<tr>
<td>''inline list-item''
<td>''list-item inline flow''
<td><a>inline box</a>
with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>
<tbody title="Formatting Context Root Display Types">
<tr>
<td>''flex''
<td>''block flex''
<td><a>block-level</a> <a>flex container</a>
<tr>
<td>''inline-flex''
<td>''inline flex''
<td><a>inline-level</a> <a>flex container</a>
<tr>
<td>''grid''
<td>''block grid''
<td><a>block-level</a> <a>grid container</a>
<tr>
<td>''inline-grid''
<td>''inline grid''
<td><a>inline-level</a> <a>grid container</a>
<tr>
<td>''ruby''
<td>''inline ruby''
<td><a>inline-level</a> <a>ruby container</a>
<tr>
<td>''block ruby''
<td>''block ruby''
<td><a>block box</a> containing <a>ruby container</a>
<tr>
<td>''table''
<td>''block table''
<td><a>block-level</a> <a>table wrapper box</a> containing <a>table box</a>
<tr>
<td>''inline-table''
<td>''inline table''
<td><a>inline-level</a> <a>table wrapper box</a> containing <a>table box</a>
<tbody title="Layout-internal display types">
<!--
<tr>
<td>''table-cell''
<td>''table-cell flow-root''
<td>table cell <a>block container</a>
<tr>
<td>''table-caption''
<td>''table-caption flow-root''
<td>table cell <a>block container</a>
<tr>
<td>''ruby-base''
<td>''ruby-base flow''
<td><a href="#layout-specific-display">layout-specific internal box</a>
<tr>
<td>''ruby-text''
<td>''ruby-text flow''
<td><a href="#layout-specific-display">layout-specific internal box</a>
-->
<tr>
<td><<display-internal>> types
<td>—
<td><a href="#layout-specific-display">layout-specific internal box</a>
</table>
Note: Following the precedence rules of “most backwards-compatible, then shortest”,
serialization of equivalent 'display' values uses the “Short 'display'” column.
[[CSSOM]]
<h3 id="outer-role">
Outer Display Roles for Flow Layout: the ''block'', ''inline'', and ''run-in'' keywords</h3>
The <<display-outside>> keywords specify the element's <a>outer display type</a>,
which is essentially its role in <a>flow layout</a>.
They are defined as follows:
<dl dfn-type="value" dfn-for="display, <display-outside>">
<dt><dfn>block</dfn>
<dd>
The element generates a <dfn dfn for>block-level box</dfn>
when placed in <a>flow layout</a>. [[!CSS2]]
<dt><dfn>inline</dfn>
<dd>
The element generates an <dfn dfn for>inline-level box</dfn>
when placed in <a>flow layout</a>. [[!CSS2]]
<dt><dfn>run-in</dfn>
<dd>
The element generates an <a>run-in box</a>,
which is a type of <a>inline-level box</a>
with special behavior that attempts to merge it into a subsequent block container.
See [[#run-in-layout]] for details.
</dl>
If a <<display-outside>> value is specified but <<display-inside>> is omitted,
the element's <a>inner display type</a> defaults to ''flow''.
<h3 id="inner-model">
Inner Display Layout Models: the ''flow'', ''flow-root'', ''table'', ''flex'', ''grid'', and ''ruby'' keywords</h3>
The <<display-inside>> keywords specify the element's <a>inner display type</a>,
which defines the type of formatting context that lays out its contents
(assuming it is a <a lt="replaced element">non-replaced element</a>).
They are defined as follows:
<dl dfn-type="value" dfn-for="display, <display-inside>">
<dt><dfn>flow</dfn>
<dd>
The element lays out its contents using <dfn dfn for>flow layout</dfn>
(<a href="https://www.w3.org/TR/CSS2/visuren.html">block-and-inline layout</a>).
If its <a>outer display type</a> is ''inline'' or ''run-in'',
and it is participating in a
<a lt="block formatting context">block</a>
or <a lt="inline formatting context">inline</a>
formatting context,
then it generates an <a>inline box</a>.
Otherwise it generates a <a>block container</a> box.
Depending on the value of other properties (such as 'position', 'float', or 'overflow')
and whether it is itself participating in a block or inline <a>formatting context</a>,
it either establishes a new <a>block formatting context</a> for its contents
or integrates its contents into its parent <a>formatting context</a>.
See <a href="https://www.w3.org/TR/CSS2/visuren.html">CSS2.1 Chapter 9</a>. [[!CSS2]]
<dt><dfn>flow-root</dfn>
<dd>
The element generates a <a>block container</a> box,
and lays out its contents using <a>flow layout</a>.
It always establishes a new <a>block formatting context</a> for its contents. [[!CSS2]]
<dt><dfn>table</dfn>
<dd>
The element generates a principal <a>table wrapper box</a>
that establishes a <a>block formatting context</a>,
and which contains
an additionally-generated <a>table box</a>
that establishes a <a>table formatting context</a>. [[!CSS2]]
<dt><dfn>flex</dfn>
<dd>
The element generates a principal <a>flex container</a> box
and establishes a <a>flex formatting context</a>. [[!CSS3-FLEXBOX]]
<dt><dfn>grid</dfn>
<dd>
The element generates a principal <a>grid container</a> box,
and establishes a <a>grid formatting context</a>. [[!CSS3-GRID-LAYOUT]]
<dt><dfn>ruby</dfn>
<dd>
The element generates a principal <a>ruby container</a> box,
and establishes a <a>ruby formatting context</a>
in addition to integrating its base-level contents
into its parent <a>formatting context</a>
if it is inline. [[!CSS3RUBY]]
</dl>
If a <<display-inside>> value is specified but <<display-outside>> is omitted,
the element's <a>outer display type</a> defaults to ''block''--
except for ''ruby'', which defaults to ''inline''.
<h3 id="list-items">
Generating Marker Boxes: the ''list-item'' keyword</h3>
The <dfn value for="display, <display-list-item>">list-item</dfn> keyword
causes the element to generate a ''::marker'' pseudo-element box [[!CSS-PSEUDO-4]]
with the content specified by its 'list-style' properties
(<a href="https://www.w3.org/TR/CSS2/generate.html#lists">CSS 2.1§12.5 Lists</a>) [[!CSS2]]
together with a principal box of the specified type for its own contents.
If no <a>inner display type</a> value is specified,
the principal box's <a>inner display type</a> defaults to ''flow''.
If no <a>outer display type</a> value is specified,
the principal box's <a>outer display type</a> defaults to ''block''.
Note: In this level, as restricted in the grammar,
list-items are limited to the <a>Flow Layout</a> display types
(''block''/''inline''/''run-in'' with ''flow''/''flow-root'' inner types).
This restriction may be relaxed in a future level of this module.
<h3 id="layout-specific-display">
Layout-Internal Display Types: the ''table-*'' and ''ruby-*'' keywords</h3>
Some layout models, such as ''table'' and ''ruby'',
have a complex internal structure,
with several different roles that their children and descendants can fill.
This section defines those “<dfn export>layout-internal</dfn>” 'display' values,
which only have meaning within that particular layout mode.
Unless otherwise specified,
both the <a>inner display type</a> and the <a>outer display type</a>
of elements using these 'display' values
are set to the given keyword.
The <<display-internal>> keywords are defined as follows:
<dl dfn-type=value dfn-for="display, <display-internal>">
<dt><dfn>table-row-group</dfn>, <dfn>table-header-group</dfn>, <dfn>table-footer-group</dfn>, <dfn>table-row</dfn>, <dfn>table-cell</dfn>, <dfn>table-column-group</dfn>, <dfn>table-column</dfn>
<dd>
The element is an <dfn dfn for>internal table element</dfn>.
It generates the appropriate <dfn dfn for>internal table box</dfn>
which participates in a <a>table formatting context</a>.
See <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">CSS2§17.2</a> [[!CSS2]].
''table-cell'' boxes have a ''flow-root'' <a>inner display type</a>.
<dt><dfn>table-caption</dfn>
<dd>
The element generates a <dfn dfn for>table caption box</dfn>,
which is a <a>block box</a> with special behavior with respect to table and table wrapper boxes.
See <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">CSS2§17.2</a> [[!CSS2]].
''table-caption'' boxes have a ''flow-root'' <a>inner display type</a>.
<dt>
<dt><dfn>ruby-base</dfn>, <dfn>ruby-text</dfn>, <dfn>ruby-base-container</dfn>, <dfn>ruby-text-container</dfn>
<dd>
The element is an <dfn dfn for>internal ruby element</dfn>.
It generates the appropriate <dfn dfn for>internal ruby box</dfn>
which participates in a <a>ruby formatting context</a>. [[!CSS3RUBY]]
''ruby-base'' and ''ruby-text'' have a ''flow'' <a>inner display type</a>.
</dl>
Boxes with layout-specific display types generate anonymous wrapper boxes around themselves
when placed in an incompatible parent,
as defined by their respective specifications.
<div class='example'>
For example, Table Layout requires that a ''table-cell'' box
must have a ''table-row'' parent box.
If it is misparented, like so:
<pre class="lang-markup">
<div style="display:block;">
<div style="display:table-cell">...</div>
</div>
</pre>
It will generate wrapper boxes around itself,
producing a structure like:
<pre>
block box
└anonymous table box
└anonymous table-row-group box
└anonymous table-row box
└table-cell box
</pre>
Even if the parent is another <a>internal table element</a>,
if it's not the <em>correct</em> one,
wrapper boxes will be generated.
For example, in the following markup:
<pre class="lang-markup">
<div style="display:table;">
<div style="display:table-row">
<div style="display:table-cell">...</div>
</div>
</div>
</pre>
Anonymous wrapper box generation will produce:
<pre>
table box
└anonymous table-row-group box
└table-row box
└table-cell box
</pre>
This "fix-up" ensures that table layout has a predictable structure to operate on.
</div>
<h3 id="box-generation">
Box Generation: the ''display/none'' and ''display/contents'' keywords</h3>
While 'display' can control the <em>types</em> of boxes an element will generate,
it can also control whether an element will generate any boxes at all.
The <<display-box>> keywords are defined as follows:
<dl dfn-type=value dfn-for="display, <display-box>">
<dt><dfn>contents</dfn>
<dd>
The element itself does not generate any boxes,
but its children and pseudo-elements still generate <a>boxes</a> and <a>text runs</a> as normal.
For the purposes of box generation and layout,
the element must be treated as if it had been replaced in the [=element tree=]
by its contents
(including both its source-document children and its pseudo-elements,
such as ''::before'' and ''::after'' pseudo-elements,
which are generated before/after the element's children as normal).
Note: As only the box tree is affected,
any semantics based on the document tree,
such as selector-matching, event handling,
and property <a>inheritance</a>,
are not affected.
This value behaves as ''display: none'' on replaced elements
and other elements whose rendering is not entirely controlled by CSS;
see [[#unbox]] for details.
Note: Replaced elements and form controls are treated specially
because removing only the element’s own generating box
is a more-or-less undefined operation.
As this behavior may be refined if use cases
(and more precise rendering models) develop,
authors should use ''display: none'' rather than ''display: contents''
on such elements for forward-compatibility.
<dt><dfn>none</dfn>
<dd>
The <a>element</a> and its descendants generate no <a>boxes</a> or <a>text runs</a>.
Similarly, if a <a>text node</a> is defined to behave as ''display: none'',
it generates no <a>text runs</a>.
</dl>
Elements with either of these values do not have <a>inner</a> or <a>outer display types</a>,
because they don't generate any boxes at all.
Note: As these values cause affected elements to not generate a box,
anonymous box generation rules will ignore the elided elements entirely,
as if they did not exist in the box tree.
Markup-based relationships, however, are not affected by these values,
as they are solely rendering-time effects.
<span class=non-normative>
For example,
although they may affect which table cell <em>appears</em> in a column,
they do not affect which table cell is associated with a particular column <em>element</em>.
Similarly, they cannot affect which HTML <{summary}> element is associated with a particular table
or whether a <{legend}> is the name of a <{fieldset}>.
</span>
<h3 id='legacy-display'>
Precomposed Inline-level Display Values</h3>
CSS level 2 used a single-keyword syntax for 'display',
requiring separate keywords for block-level and inline-level variants of the same layout mode.
These <<display-legacy>> keywords map as follows:
<dl dfn-type=value dfn-for="display, <display-legacy>">
<dt><dfn>inline-block</dfn>
<dd>
Behaves as ''inline flow-root''.
<dt><dfn>inline-table</dfn>
<dd>
Behaves as ''inline table''.
<dt><dfn>inline-flex</dfn>
<dd>
Behaves as ''inline flex''.
<dt><dfn>inline-grid</dfn>
<dd>
Behaves as ''inline grid''.
</dl>
<h3 id='transformations'>
Automatic Box Type Transformations</h3>
Some layout effects require <dfn export lt="blockify|blockification">blockification</dfn>
or <dfn export lt="inlinify|inlinification">inlinification</dfn> of the box type,
which sets the box’s <a>outer display type</a>
to ''block'' or ''inline'' (respectively).
(This has no effects on <a>display types</a> that generate no box at all,
such as ''display/none'' or ''display/contents''.)
<div class='example'>
Some examples of this include:
<ul>
<li>Absolute positioning or floating an element <a>blockifies</a> the box’s display type. [[CSS2]]
<li>Containment in a <a spec=css-ruby>ruby container</a> <a>inlinifies</a> the box’s display type, as described in [[CSS3RUBY]].
<li>A parent with a ''grid'' or ''flex'' 'display' value <a>blockifies</a> the box’s display type. [[CSS3-GRID-LAYOUT]] [[CSS3-FLEXBOX]]
</ul>
</div>
If a ''block flow'' box is <a>inlinified</a>,
its <a>inner display type</a> is set to ''flow-root''
so that it remains a block container.
If an ''inline flow'' box is <a>inlinified</a>,
it recursively <a>inlinifies</a> all of its in-flow children,
so that no block-level descendants
break up the inline formatting context in which it participates.
If a [=layout-internal=] box is <a>blockified</a>,
its [=inner display type=] converts to ''flow''
so that it becomes a <a>block container</a>.
<a>Inlinification</a> has no effect on <a>layout-internal</a> boxes.
(However, placement in such an inline context
will typically cause them to be wrapped
in an appropriately-typed anonymous inline-level box.)
The root element’s display type is always <a>blockified</a>.
Additionally, a 'display' of ''display/contents'' computes to ''block'' on the root element.
Note: There are two methods used to fix up box types when a box is mismatched to its context.
One is transformation of the <a>computed value</a> of 'display', such as <a>blockification</a> and <a>inlinification</a> described here.
The other, taking place during [[#intro|box tree construction]] (after computed values have been determined),
is the creation of intermediary anonymous boxes,
such as happens in <a href="https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes">tables</a>,
[[css-ruby-1#box-fixup|ruby]],
and <a href="https://www.w3.org/TR/CSS21/visuren.html#box-gen">flow</a> layout.
<!--
<h2 id='box-suppress'>
Toggling Box Generation: the 'display-or-not' property</h2>
<pre class="propdef">
Name: display-or-not
Value: show | discard | hide
Initial: show
Applies to: all elements
Inherited: no
Percentages: n/a
Computed value: as specified
Media: all
</pre>
The ''display: none'' value was historically used as a "toggle"
to switch between showing and hiding an element.
Making this reversible requires either setting up the CSS <a>cascade</a> carefully,
or remembering what the 'display' value was before it was set to ''display/none''.
To make this common use-case easier,
this module introduces the separate 'display-or-not' property to do the same thing,
so that toggling whether or not an element appears in the formatting tree
can now be done without affecting its display type when it <em>is</em> displayed.
Issue: This property (which needs a better name)
along with a <css>display-type</css> (or possibly <css>display-as</css>) longhand
which takes all values of 'display' other than ''display/none'',
are intended to be longhands of 'display'.
This has not yet been edited in, as this split feature is likely to be deferred to the next level
in order to have time to thoroughly work through and accommodate the
<a href="https://lists.w3.org/Archives/Public/www-style/2016Aug/0025.html">various use cases</a> for showing/hiding an element.
Values have the following meanings:
<dl dfn-type="value" dfn-for="display-or-not">
<dt><dfn>show</dfn>
<dd>
The element generates boxes as normal,
per its 'display-*' properties.
<dt><dfn>discard</dfn>
<dd>
The element generates no boxes at all.
<dt><dfn>hide</dfn>
<dd>
The element generates boxes as normal,
but those boxes do not participate in layout in any way,
and must not be displayed.
For the purpose of any layout-related information,
such as querying for the computed value of the element's 'width' property,
it must be treated as if it did not generate any boxes.
Properties that rely on boxes but do not rely on layout,
such as animations, 'counter-increment', etc.,
must work as normal on this element and its descendants.
Issue: This needs more clarity about what "layout-related" and "participates in layout" means.
Does the box still generate anonymous boxes, etc.? How does it affect speech?
See <a href="https://lists.w3.org/Archives/Public/www-style/2015Jun/0346.html">proposal</a>.
</dl>
Issue: We welcome better naming suggestions on this property.
Issue: Please send use cases (examples of where this property or something close to it is useful and necessary)
<a href="mailto:www-style@w3.org?subject=%5Bcss-display%5D%20box-suppres%20use%20cases">to the CSSWG</a> so that we can be sure we're designing the details of its behavior correctly.
-->
<h2 id='run-in-layout'>
Run-In Layout</h2>
A <dfn export lt="run-in | run-in box">run-in box</dfn>
is a box that <em>merges into</em> a block that comes after it,
inserting itself at the beginning of that block’s inline-level content.
This is useful for formatting compact headlines, definitions, and other similar things,
where the appropriate DOM structure is to have a headline preceding the following prose,
but the desired display is an inline headline laying out with the text.
<div class="example">
For example, dictionary definitions are often formatted so that the word is inline with the definition:
<pre>
<dl class='dict'>
<dt>dictionary
<dd>a book that lists the words of a language in alphabetical
order and gives their meaning, or that gives the equivalent
words in a different language.
<dt>glossary
<dd>an alphabetical list of terms or words found in or relating
to a specific subject, text, or dialect, with explanations; a
brief dictionary.
</dl>
<style>
.dict > dt {
display: run-in;
}
.dict > dt::after {
content: ": "
}
</style>
</pre>
Which is formatted as:
<pre>
<b>dictionary:</b> a book that lists the words of a language
in alphabetical order and explains their meaning.
<b>glossary:</b> an alphabetical list of terms or words found
in or relating to a specific subject, text, or dialect,
with explanations; a brief dictionary.
</pre>
</div>
A <a>run-in box</a> behaves exactly as any other <a>inline-level box</a>, except:
<ul>
<li>
A <a>run-in box</a> with a ''flow'' <a>inner display type</a> <a>inlinifies</a> its contents.
<li>
If a <a>run-in sequence</a> is immediately followed by a block box
that does not establish a new <a>block formatting context</a>,
it is inserted as direct children of the block box
after its ''::marker'' pseudo-element's boxes (if any),
but preceding any other boxes generated by the contents of the block
(including the box generated by the ''::before'' pseudo-element, if any).
This step recurses if possible
(so that the run-in effectively becomes
part of the deepest subsequent “paragraph” in its formatting context).
The reparented content is then formatted as if originally parented there.
<span class='note'>Note that only layout is affected, not inheritance,
because property inheritance for non-anonymous boxes is based only on the element tree.</span>
<li>
Otherwise,
an anonymous block box is generated around the <a>run-in sequence</a>
and all immediately following inline-level content
(up to, but not including, the next <a>run-in sequence</a>, if any).
</ul>
A <dfn>run-in sequence</dfn> is a maximal sequence of consecutive sibling <a>run-in boxes</a>
and intervening white space and/or out-of-flow boxes.
Note: This statement implies that out-of-flow boxes are reparented
if they are between two run-in boxes.
Another alternative would be to leave behind the intervening out-of-flow boxes,
or to have out-of-flow boxes impede the running-in of earlier boxes.
Implementers and authors are encouraged to contact the CSSWG if they have a preferred behavior, as this one was picked somewhat at random.
This fixup occurs before the anonymous block and inline box fixup described in <a href="https://www.w3.org/TR/CSS21/visuren.html#box-gen">CSS2§9.2</a>,
and affects the determination of the <a>first formatted line</a>
of the affected elements
as if the <a>run-in sequence</a> were originally
in its final location in the box tree.
Note: As the earliest run-in represents the first text on the <a>first formatted line</a> of its containing block,
a ''::first-letter'' pseudo-element applied to that block element
selects the first letter of the run-in,
rather than the first letter of its own contents.
Note: This run-in model is slightly different from the one proposed in earlier revisions of [[!CSS2]].
<h2 id='glossary' class=no-num>
Appendix A: Glossary</h2>
The following terms are defined here for convenience:
<dl export>
<dt><dfn>principal box</dfn>
<dd>
When an [=element=] generates one or more [=boxes=],
one of them is the [=principal box=],
which contains its descendant boxes and generated content,
and is also the box involved in any positioning scheme.
Some elements may generate additional boxes in addition to the principal box
(such as ''display/list-item'' elements,
which generate an additional marker box,
or ''display/table'' elements,
which generate a [=principal box|principal=] [=table wrapper box=]
and an additional [=table box=]).
These additional boxes are placed with respect to the principal box.
<dt><dfn lt="inline-level|inline-level content">inline-level</dfn>
<dd>
Content that participates in inline layout.
Specifically, inline-level boxes and text.
<dt><dfn lt="block-level|block-level content">block-level</dfn>
<dd>
Content that participates in block layout.
Specifically, block-level boxes.
<dt><dfn>inline box</dfn>
<dd>
A non-replaced <a>inline-level</a> box whose <a>inner display type</a> is ''flow''.
The contents of an inline box participate in the same inline formatting context as the inline box itself.
<dt><dfn>inline</dfn>
<dd>
Used as a shorthand for <a>inline box</a> or <a>inline-level box</a>
where unambiguous,
or as an adjective meaning <a>inline-level</a>.
The latter usage is deprecated.
<dt><dfn lt="atomic inline|atomic inline box">atomic inline</dfn>
<dd>
An inline-level box that is replaced (such as an image)
or that establishes a new formatting context (such as an ''inline-block'' or ''inline-table'')
and cannot split across lines
(as <a>inline boxes</a> and <a>ruby containers</a> can).
Any inline-level box whose <a>inner display type</a> is not ''flow''
establishes a new formatting context of the specified <a>inner display type</a>.
<dt><dfn lt="block container|block container box">block container</dfn>
<dd>
A block container either contains only inline-level boxes
participating in an <a>inline formatting context</a>,
or contains only block-level boxes
participating in a <a>block formatting context</a>
(possibly generating anonymous block boxes to ensure this constraint,
as defined in <a href="https://www.w3.org/TR/CSS2/visuren.html#anonymous-block-level">CSS2§9.2.1.1</a>).
A block container that contains only inline-level content
establishes a new <a>inline formatting context</a>.
The element then also generates a <a>root inline box</a>
which wraps all of its inline content.
<span class=note>Note, this <a>root inline box</a> concept
effectively replaces the "anonymous inline element" concept
introduced in <a href="https://www.w3.org/TR/CSS2/visuren.html#anonymous">CSS2§9.2.2.1</a>.</span>
A block container that contains only block-level boxes
establishes a new <a>block formatting context</a>
if its parent formatting context is <em>not</em> a <a>block formatting context</a>;
otherwise, when participating in a <a>block formatting context</a> itself,
it either establishes a new <a>block formatting context</a> for its contents
or continues the one in which it participates,
as determined by the constraints of other properties
(such as 'overflow' or 'align-content').
<dt><dfn>block box</dfn>
<dd>
A <a>block-level box</a> that is also a <a>block container</a>.
Note: Not all <a>block container</a> boxes are <a>block-level</a> boxes:
non-replaced inline blocks and non-replaced table cells,
for example, are block containers
but not block-level boxes.
Similarly, not all block-level boxes are block containers:
block-level replaced elments (''display: block'')
and flex containers (''display: flex''), for example,
are not block containers.
<dt><dfn>block</dfn>
<dd>
Used as a shorthand for <a>block box</a>, <a>block-level box</a>, or <a>block container box</a>,
where unambiguous.
<dt><dfn lt="replaced element|replaced">replaced element</dfn>
<dd>
An element whose content is outside the scope of the CSS formatting model,
such as an image, embedded document, or applet.
<span class=non-normative>
For example, the content of the HTML <{img}> element
is often replaced by the image that its <{img/src}> attribute designates.
</span>
Replaced elements often have intrinsic dimensions:
an intrinsic width, an intrinsic height, and an intrinsic ratio.
For example, a bitmap image has an intrinsic width and an intrinsic height specified in absolute units
(from which the intrinsic ratio can obviously be determined).
On the other hand, other documents may not have any intrinsic dimensions
(for example, a blank HTML document).
User agents may consider a replaced element to not have any intrinsic dimensions
if it is believed that those dimensions could leak sensitive information to a third party.
For example, if an HTML document changed intrinsic size depending on the user's bank balance,
then the UA might want to act as if that resource had no intrinsic dimensions.
The content of replaced elements is not considered in the CSS formatting model;
however, their intrinsic dimensions are used in various layout calculations.
A <dfn>non-replaced</dfn> element is one that is not <a>replaced</a>,
i.e. whose rendering is dictated by the CSS model.
<dt><dfn>containing block</dfn>
<dd>
A rectangle that forms the basis of sizing and positioning
for the boxes associated with it
(usually the children of the box that generated it).
Notably, a containing block is <em>not a box</em>
(it is a rectangle),
however it is often derived from the dimensions of a box.
If properties of a containing block are referenced,
they reference the values on the box that generated the containing block.
(For the <a>initial containing block</a>, the values are taken from the root element.)
See [[CSS2]] <a href="https://www.w3.org/TR/CSS2/visuren.html#containing-block">Section 9.1.2</a>
and <a href="https://www.w3.org/TR/CSS2/visudet.html#containing-block-details">Section 10.1</a> for details.
<dt><dfn>containing block chain</dfn>
<dd>
A sequence of successive <a>containing blocks</a>
that form an ancestor-descendant chain
through the <a>containing block</a> relation.
For example, an <a>inline box</a>’s containing block is the content box of its closest <a>block container</a> ancestor;
if that block container is an in-flow <a>block</a>,
then <em>its</em> containing block is formed by its parent <a>block container</a>;
if that grandparent <a>block container</a> is <a>absolutely positioned</a>,
then <em>its</em> containing block is the padding edges of its closest <em>positioned</em> ancestor (not necessarily its parent),
and so on up to the <a>initial containing block</a>.
<dt><dfn>initial containing block</dfn>
<dd>
The <a>containing block</a> of the root element.
See <a href="https://www.w3.org/TR/CSS2/visudet.html#containing-block-details">CSS2.1§10.1</a> for continuous media;
and [[!CSS3PAGE]] for paged media.
<dt><dfn>formatting context</dfn>
<dd>
A <a>formatting context</a> is the environment
into which a set of related boxes are laid out.
Different formatting contexts lay out their boxes
according to different rules.
For example, a <a>flex formatting context</a>
lays out boxes according to the <a>flex layout</a> rules [[CSS3-FLEXBOX]],
whereas a <a>block formatting context</a>
lays out boxes according to the block-and-inline layout rules [[CSS2]].
When a box establishes a <em>new</em> formatting context
(whether that formatting context is of the same type as its parent or not),
it essentially creates a new, independent layout environment:
except through the sizing of the box itself,
the layout of its descendants is (generally)
not affected by the the rules and contents of
the formatting context outside the box, and vice versa.
<p class="example">
For example, in a <a>block formatting context</a>,
floated boxes affect the layout of surrounding boxes.
But their effects do not escape their <a>formatting context</a>:
the box establishing their <a>formatting context</a> grows to fully contain them,
and floats from outside that box
are not allowed to protrude into and affect the contents
inside the box.
<p class="example">
As another example, margins do not collapse across formatting context boundaries.
<p class="note">
Exclusions are able to affect content across formatting context boundaries.
(At time of writing, they are the only layout feature that can.)
[[CSS3-EXCLUSIONS]]
<dt><dfn>block formatting context</dfn>
<dt><dfn>inline formatting context</dfn>
<dd>
Block and inline formatting contexts are defined in
<a href="https://www.w3.org/TR/CSS2/visuren.html#normal-flow">CSS 2.1 Section 9.4</a>.