-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
4660 lines (3921 loc) · 204 KB
/
Overview.bs
File metadata and controls
4660 lines (3921 loc) · 204 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 Grid Layout Module Level 1
Status: ED
Work Status: Testing
Shortname: css-grid
Level: 1
Group: csswg
ED: https://drafts.csswg.org/css-grid/
TR: https://www.w3.org/TR/css-grid-1/
Previous version: https://www.w3.org/TR/2016/WD-css-grid-1-20160519/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150917/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150806/
Previous version: https://www.w3.org/TR/2015/WD-css-grid-1-20150317/
Previous version: https://www.w3.org/TR/2014/WD-css-grid-1-20140513/
Previous version: https://www.w3.org/TR/2014/WD-css-grid-1-20140123/
Previous version: https://www.w3.org/TR/2013/WD-css3-grid-layout-20130402/
Previous version: https://www.w3.org/TR/2012/WD-css3-grid-layout-20121106/
Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885
Former editor: Alex Mogilevsky, Microsoft Corporation, alexmog@microsoft.com
Former editor: Phil Cupp, Microsoft Corporation, pcupp@microsoft.com
Issue Tracking: Disposition of Comments https://drafts.csswg.org/css-grid-1/issues
Abstract: This CSS module defines a two-dimensional grid-based layout system, optimized for user interface design. In the grid layout model, the children of a grid container can be positioned into arbitrary slots in a predefined flexible or fixed-size layout grid.
Ignored Terms: containing block, <positive-integer>, <ident>, auto, grid-*-start, grid-*-end, flex factor, flex factors, block formatting context, grid-auto-position, min size property, max size property
Ignored Vars: A, B, C, size-contribution, track-sizes, extra-space
Link Defaults: css21 (property) margin/min-height/max-height/min-width/max-width, css-align-3 (value) stretch/baseline, css-position-3 (property) left, css-position-3 (property) position, css-writing-modes-3 (dfn) start/end
At Risk: application of grid placement to absolutely-positioned boxes
</pre>
<pre class="link-defaults">
spec:css-align-3;
type:value;
text:stretch; for:align-self
text:stretch; for:align-content
text:space-between; for:justify-content
text:space-around; for:justify-content
type:property; text:column-gap
spec:css-break-3; type:dfn; text:fragment
spec:css-flexbox-1; type:dfn
text: specified size
text: content size
text: transferred size
spec:css-pseudo-4; type:selector;
text:::first-line
text:::first-letter
</pre>
<style>
.example {
clear:both
}
.pseudo-code {
font-family:monospace
}
.pseudo-code > ol {
list-style-type:decimal
}
.pseudo-code > ol > li > ol {
list-style-type:lower-latin
}
.pseudo-code > ol > li > ol > li > ol {
list-style-type:lower-roman
}
.pseudo-code ul {
list-style-type:disc
}
dd > p:nth-child(1) {
margin-top:0
}
dd:last-child {
margin-bottom: 0;
}
dl.phase {
padding-left: .5em;
border-left: .5em #e0e0e0 solid;
}
#grid-property-breakdown tr:nth-child(3) td {
width: 25%;
border-style: solid;
}
</style>
Issue: If you notice any inconsistencies between this Grid Layout Module
and the <a href="http://www.w3.org/TR/css-flexbox/">Flexible Box Layout Module</a>,
please report them to the CSSWG,
as this is likely an error.
<h2 id='intro'>
Introduction</h2>
<em>This section is not normative.</em>
Grid Layout is a new layout model for CSS
that has powerful abilities to control the sizing and positioning of boxes and their contents.
Unlike <a href="http://www.w3.org/TR/css-flexbox-1/">Flexible Box Layout</a>, which is single-axis–oriented,
Grid Layout is optimized for 2-dimensional layouts:
those in which alignment of content is desired in both dimensions.
<figure>
<img src="images/flex-layout.png"
alt="An example of flex layout:
two rows of items,
the first being three items a third of the space each,
and the second being five items, a fifth of the space each.
There is therefore alignment along the row axis, but not along the column axis.">
<figcaption>Exemplary Flex Layout Example</figcaption>
</figure>
<figure>
<img src="images/grid-layout.png"
alt="An example of grid layout:
two rows of items,
the first being four items—the last of which spans both rows,
and the second being two items—the first of which spans the first two columns— plus the spanned item from the first row.">
<figcaption>Exemplary Grid Layout Example</figcaption>
</figure>
In addition, due to its ability to explicitly position items in the grid,
Grid Layout allows dramatic transformations in visual layout structure
without requiring corresponding markup changes.
By combining <a href="http://www.w3.org/TR/css3-mediaqueries/">media queries</a> with the CSS properties that control layout of the grid container and its children,
authors can adapt their layout to changes in device form factors, orientation, and available space,
while preserving a more ideal semantic structuring of their content
across presentations.
Although many layouts can be expressed with either Grid or Flexbox,
they each have their specialties.
Grid enforces 2-dimensional alignment,
uses a top-down approach to layout,
allows explicit overlapping of items,
and has more powerful spanning capabilities.
Flexbox focuses on space distribution within an axis,
uses a simpler bottom-up approach to layout,
can use a content-size–based line-wrapping system to control its secondary axis,
and relies on the underlying markup hierarchy
to build more complex layouts.
It is expected that both will be valuable
and complementary tools for CSS authors.
<h3 id='background'>
Background and Motivation</h3>
<figure class="sidefigure">
<img class="figure" alt="Image: Application layout example requiring horizontal and vertical alignment." src="images/basic-form.png" />
<figcaption>Application layout example requiring horizontal and vertical alignment.</figcaption>
</figure>
As websites evolved from simple documents into complex, interactive applications,
techniques for document layout, e.g. floats,
were not necessarily well suited for application layout.
By using a combination of tables, JavaScript, or careful measurements on floated elements,
authors discovered workarounds to achieve desired layouts.
Layouts that adapted to the available space were often brittle
and resulted in counter-intuitive behavior as space became constrained.
As an alternative, authors of many web applications opted for a fixed layout
that cannot take advantage of changes in the available rendering space on a screen.
The capabilities of grid layout address these problems.
It provides a mechanism for authors to divide available space for layout into columns and rows
using a set of predictable sizing behaviors.
Authors can then precisely position and size the building block elements of their application
into the <a>grid areas</a> defined by the intersections of these columns and rows.
The following examples illustrate the adaptive capabilities of grid layout,
and how it allows a cleaner separation of content and style.
<h4 id='adapting-to-available-space'>
Adapting Layouts to Available Space</h4>
<figure class="sidefigure">
<img src="images/game-smaller.png"
alt="Let us consider the layout of a game in two columns and three rows: the game title in the top left corner, the menu below it, and the score in the bottom left with the game board occupying the top and middle cells on the right followed by game controls filling the bottom left. The left column is sized to exactly fit its contents (the game title, menu items, and score), with the right column filling the remaining space."/>
<figcaption>Five grid items arranged according to content size and available space.</figcaption>
</figure>
<figure class="sidefigure">
<img src="images/game-larger.png"
alt="As more space becomes available in larger screens, the middle row / right column are allowed to expand to fill that space." />
<figcaption>Growth in the grid due to an increase in available space.</figcaption>
</figure>
Grid layout can be used to intelligently resize elements within a webpage.
The adjacent figures represent a game with five major components in the layout:
the game title, stats area, game board, score area, and control area.
The author's intent is to divide the space for the game such that:
<ul>
<li>
The stats area always appears immediately under the game title.
<li>
The game board appears to the right of the stats and title.
<li>
The top of the game title and the game board should always align.
<li>
The bottom of the game board and bottom of the stats area align when the game has reached its minimum height.
In all other cases the game board will stretch to take advantage of all the space available to it.
<li>
The controls are centered under the game board.
<li>
The top of the score area is aligned to the top of the controls area.
<li>
The score area is beneath the stats area.
<li>
The score area is aligned to the controls beneath the stats area.
</ul>
The following grid layout example shows how an author might achieve
all the sizing, placement, and alignment rules declaratively.
<div class="example">
<pre class="lang-css">
/**
* Define the space for each <a>grid item</a> by declaring the grid
* on the <a>grid container</a>.
*/
#grid {
/**
* Two columns:
* 1. the first sized to content,
* 2. the second receives the remaining space
* (but is never smaller than the minimum size of the board
* or the game controls, which occupy this column [Figure 4])
*
* Three rows:
* 3. the first sized to content,
* 4. the middle row receives the remaining space
* (but is never smaller than the minimum height
* of the board or stats areas)
* 5. the last sized to content.
*/
display: grid;
grid-template-columns:
/* 1 */ auto
/* 2 */ 1fr;
grid-template-rows:
/* 3 */ auto
/* 4 */ 1fr
/* 5 */ auto;
}
/* Specify the position of each <a>grid item</a> using coordinates on
* the 'grid-row' and 'grid-column' properties of each <a>grid item</a>.
*/
#title { grid-column: 1; grid-row: 1; }
#score { grid-column: 1; grid-row: 3; }
#stats { grid-column: 1; grid-row: 2; align-self: start; }
#board { grid-column: 2; grid-row: 1 / span 2; }
#controls { grid-column: 2; grid-row: 3; justify-self: center; }
</pre>
<pre class="lang-markup">
<div id="grid">
<div id="title">Game Title</div>
<div id="score">Score</div>
<div id="stats">Stats</div>
<div id="board">Board</div>
<div id="controls">Controls</div>
</div>
</pre>
</div>
Note: There are multiple ways to specify the structure of the grid
and to position and size <a>grid items</a>,
each optimized for different scenarios.
<h4 id='source-independence'>
Source-Order Independence</h4>
<figure class="sidefigure">
<img alt="Image: An arrangement suitable for portrait orientation." src="images/game-portrait.png" />
<figcaption>An arrangement suitable for “portrait” orientation.</figcaption>
</figure>
<figure class="sidefigure">
<img alt="Image: An arrangement suitable for landscape orientation." src="images/game-landscape.png" />
<figcaption>An arrangement suitable for “landscape“ orientation.</figcaption>
</figure>
Continuing the prior example,
the author also wants the game to adapt to different devices.
Also, the game should optimize the placement of the components when viewed either in portrait or landscape orientation (Figures 6 and 7).
By combining grid layout with media queries,
the author is able to use the same semantic markup,
but rearrange the layout of elements independent of their source order,
to achieve the desired layout in both orientations.
The following example uses grid layout’s ability to name the space which will be occupied by a <a>grid item</a>.
This allows the author to avoid rewriting rules for <a>grid items</a>
as the grid’s definition changes.
<div class="example">
<pre class="lang-css">
@media (orientation: portrait) {
#grid {
display: grid;
/* The rows, columns and areas of the grid are defined visually
* using the grid-template-areas property. Each string is a row,
* and each word an area. The number of words in a string
* determines the number of columns. Note the number of words
* in each string must be identical. */
grid-template-areas: "title stats"
"score stats"
"board board"
"ctrls ctrls";
/* The way to size columns and rows can be assigned with the
* grid-template-columns and grid-template-rows properties. */
grid-template-columns: auto 1fr;
grid-template-rows: auto auto 1fr auto;
}
}
@media (orientation: landscape) {
#grid {
display: grid;
/* Again the template property defines areas of the same name,
* but this time positioned differently to better suit a
* landscape orientation. */
grid-template-areas: "title board"
"stats board"
"score ctrls";
grid-template-columns: auto 1fr;
grid-template-rows: auto 1fr auto;
}
}
/* The grid-area property places a grid item into a named
* area of the grid. */
#title { grid-area: title }
#score { grid-area: score }
#stats { grid-area: stats }
#board { grid-area: board }
#controls { grid-area: ctrls }
</pre>
<pre class="lang-markup">
<div id="grid">
<div id="title">Game Title</div>
<div id="score">Score</div>
<div id="stats">Stats</div>
<div id="board">Board</div>
<div id="controls">Controls</div>
</div>
</pre>
</div>
Note: The reordering capabilities of grid layout intentionally affect
<em>only the visual rendering</em>,
leaving speech order and navigation based on the source order.
This allows authors to manipulate the visual presentation
while leaving the source order intact and optimized for non-CSS UAs
and for linear models such as speech and sequential navigation.
Advisement: Grid item placement and reordering must not be used
as a substitute for correct source ordering,
as that can ruin the accessibility of the document.
<h2 id='overview'>
Overview</h2>
<em>This section is not normative.</em>
Grid Layout controls the layout of its content
through the use of a <a>grid</a>:
an intersecting set of horizontal and vertical lines
which create a sizing and positioning coordinate system
for the <a>grid container</a>’s contents.
Grid Layout features
<ul>
<li>
fixed, flexible, and content-based <a href="#track-sizing">track sizing functions</a>
<li>
<a href="#placement">explicit item placement</a> via forwards (positive) and backwards (negative) numerical grid coordinates,
named grid lines, and named grid areas;
automatic item placement into empty areas, including <a href="#order-property">reordering with <css>order</css></a>
<li>
space-sensitive track repetition
and
automatic addition of rows or columns to accommodate additional content
<li>
control over alignment and spacing with
<a href="#auto-margins">margins</a>, <a>gutters</a>, and the <a href="http://www.w3.org/TR/css-align/">alignment properties</a>
<li>
the ability to overlap content and <a href="#z-order">control layering with <css>z-index</css></a>
</ul>
<a>Grid containers</a> can be nested or mixed with <a>flex containers</a>
as necessary to create more complex layouts.
<h3 id="overview-grid">
Declaring the Grid</h3>
The <a>tracks</a> (<a>rows</a> and <a>columns</a>) of the <a>grid</a>
are declared and sized
either explicitly through the <a>explicit grid</a> properties
or are implicitly created when items are placed outside the <a>explicit grid</a>.
The 'grid' shorthand and its sub-properties define the parameters
of the grid.
[[#grid-definition]]
<div class="example">
Below are some examples of grid declarations:
<ul>
<li>
The following declares a grid with four named areas:
<code>H</code>, <code>A</code>, <code>B</code>,
and <code>F</code>.
The first column is sized to fit its contents (''grid-template-columns/auto''),
and the second column takes up the remaining space (<a value lt=fr>1fr</a>).
Rows default to ''grid-template-rows/auto'' (content-based) sizing;
the last row is given a fixed size of ''30px''.
<pre>
main {
grid: "H H "
"A B "
"F F " 30px
/ auto 1fr;
}
</pre>
<li>
The following declares a grid with as many rows of at least ''5em''
as will fit in the height of the grid container (''100vh'').
The grid has no explicit columns;
instead columns are added as content is added,
the resulting column widths are equalized (<a value lt=fr>1fr</a>).
Since content overflowing to the right won't print,
an alternate layout for printing adds rows instead.
<pre>
main {
grid: repeat(auto-fill, 5em) / auto-flow 1fr;
height: 100vh;
}
@media print {
main {
grid: auto-flow 1fr / repeat(auto-fill, 5em);
}
}
</pre>
<li>
The following declares a grid with 5 evenly-sized columns
and three rows,
with the middle row taking up all remaining space
(and at least enough to fit its contents).
<pre>
main {
grid: auto 1fr auto / repeat(5, 1fr);
min-height: 100vh;
}
</pre>
</ul>
</div>
<h3 id="overview-placement">
Placing Items</h3>
The contents of the <a>grid container</a> are organized into individual <a>grid items</a>
(analogous to <a>flex items</a>),
which are then assigned to predefined [=grid areas|areas=] in the <a>grid</a>.
They can be explicitly placed using coordinates through the <a>grid-placement properties</a>
or implicitly placed into empty areas using <a href="#auto-placement">auto-placement</a>.
[[#placement]]
<div class="example">
Below are some examples of grid placement declarations
using the 'grid-area' shorthand:
<pre>
grid-area: a; /* Place into named grid area “a” */
grid-area: auto; /* Auto-place into next empty area */
grid-area: 2 / 4; /* Place into row 2, column 4 */
grid-area: 1 / 3 / -1; /* Place into column 3, span all rows */
grid-area: header-start / sidebar-start / footer-end / sidebar-start;
/* Place using named lines */
</pre>
These are equivalent to the following 'grid-row' + 'grid-column' declarations:
<pre>
grid-row: a; grid-column: a;
grid-row: auto; grid-column: auto;
grid-row: 2; grid-column: 4;
grid-row: 1 / -1; grid-column: 3;
grid-row: header-start / footer-end; grid-column: sidebar-start / footer-end;
</pre>
They can further be decomposed into the 'grid-row-start'/'grid-row-end'/'grid-column-start'/'grid-column-end' longhands, e.g.
<pre>
grid-area: a;
/* Equivalent to grid-row-start: a; grid-column-start: a; grid-row-end: a; grid-column-end: a; */
grid-area: 1 / 3 / -1;
/* Equivalent to grid-row-start: 1; grid-column-start: 3; grid-row-end: -1; grid-column-end: auto; */
</pre>
</div>
<h3 id="overview-sizing">
Sizing the Grid</h3>
Once the <a>grid items</a> have been <a href="#placement">placed</a>,
the sizes of the <a>grid tracks</a> (rows and columns) are calculated,
accounting for the sizes of their contents and/or available space as specified in the grid definition.
The resulting sized grid is <a href="#grid-align">aligned</a> within the <a>grid container</a>
according to the <a>grid container</a>’s 'align-content' and 'justify-content' properties.
[[#alignment]]
<div class="example">
The following example justifies all columns
by distributing any extra space among them,
and centers the grid in the <a>grid container</a>
when it is smaller than 100vh.
<pre>
main {
grid: auto-flow 1fr / repeat(auto-fill, 5em);
min-height: 100vh;
justify-content: space-between;
align-content: safe center;
}
</pre>
</div>
Finally each <a>grid item</a> is sized and aligned within its assigned <a>grid area</a>,
as specified by its own <a href="https://www.w3.org/TR/CSS2/visudet.html">sizing</a> [[!CSS21]] and <a lt="box alignment properties">alignment properties</a> [[!CSS-ALIGN-3]].
<!--
██████ ███████ ██ ██ ██████ ████████ ████████ ████████ ██████
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██████ ████████ ██ ██████
██ ██ ██ ██ ████ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██
██████ ███████ ██ ██ ██████ ████████ ██ ██ ██████
-->
<h2 id='grid-concepts'>
Grid Layout Concepts and Terminology</h2>
In <dfn export>grid layout</dfn>,
the content of a <a>grid container</a> is laid out
by positioning and aligning it into a <a>grid</a>.
The <dfn export>grid</dfn> is an intersecting set of horizontal and vertical <a>grid lines</a>
that divides the <a>grid container</a>’s space into <a>grid areas</a>,
into which <a>grid items</a> (representing the <a>grid container</a>’s content) can be placed.
There are two sets of <a>grid lines</a>:
one set defining <dfn export lt="grid column" local-lt="column">columns</dfn>
that run along the <a href="https://www.w3.org/TR/css3-writing-modes/#block-axis">block axis</a> (the <dfn export>column axis</dfn>),
and an orthogonal set defining <dfn export lt="grid row" local-lt="row">rows</dfn>
along the <a href="https://www.w3.org/TR/css3-writing-modes/#inline-axis">inline axis</a> (the <dfn export>row axis</dfn>).
[[!CSS3-WRITING-MODES]]
<!--
<div class="figure">
<img class="figure" alt="Image: A diagram illustrating the relationship between the Grid Element and its Tracks, Lines, Areas and Items." src="images/grid-concepts.png" />
<p class="caption">A diagram illustrating the relationship between the <a>grid container</a> and its tracks, lines, areas and items.
</div>
-->
<figure>
<img class="figure" alt="Image: Grid Lines." src="images/grid-lines.png" />
<figcaption>Grid lines: Three in the block axis and four in the inline axis.</figcaption>
</figure>
Note: The “column axis” term as used here was chosen to match the <a>block axis</a>
because this matches the visual orientation of the column boxes themselves
and matches the direction that a column grows as more items are added to it.
As a result, it does not match the axis in which new columns are added
or in which their track size is measured,
which is the <a lt="inline axis">inline</a> or <a>row axis</a>
The opposite logic, of course, applies to the “row axis”.
<h3 id="grid-line-concept">
Grid Lines</h3>
<dfn id='grid-line' export lt='grid line|grid row line|grid column line'>Grid lines</dfn> are the horizontal and vertical dividing lines of the <a>grid</a>.
A <a>grid line</a> exists on either side of a column or row.
They can be referred to by numerical index,
or by an author-specified name.
A <a>grid item</a> references the <a>grid lines</a> to determine its position within the <a>grid</a>
using the <a href="#placement">grid-placement properties</a>.
<div class="example">
The following two examples both create three column <a>grid lines</a> and four row <a>grid lines</a>.
This first example demonstrates how an author would position a <a>grid item</a> using <a>grid line</a> numbers:
<pre class="lang-css">
#grid {
display: grid;
grid-template-columns: 150px 1fr;
grid-template-rows: 50px 1fr 50px;
}
#item1 { grid-column: 2;
grid-row-start: 1; grid-row-end: 4; }
</pre>
This second example uses explicitly named <a>grid lines</a>:
<pre class="lang-css">
/* equivalent layout to the prior example, but using named lines */
#grid {
display: grid;
grid-template-columns: 150px [item1-start] 1fr [item1-end];
grid-template-rows: [item1-start] 50px 1fr 50px [item1-end];
}
#item1 {
grid-column: item1-start / item1-end;
grid-row: item1-start / item1-end;
}
</pre>
</div>
<h3 id="grid-track-concept">
Grid Tracks and Cells</h3>
<dfn export local-lt="track">Grid track</dfn> is a generic term for a <a>grid column</a> or <a>grid row</a>—in
other words, it is the space between two adjacent <a>grid lines</a>.
Each <a>grid track</a> is assigned a sizing function,
which controls how wide or tall the column or row may grow,
and thus how far apart its bounding <a>grid lines</a> are.
Adjacent <a>grid tracks</a> can be separated by <a href="#gutters">gutters</a>
but are otherwise packed tightly.
A <dfn export>grid cell</dfn> is the intersection of a grid row and a grid column.
It is the smallest unit of the grid that can be referenced when positioning <a>grid items</a>.
<div class="example">
In the following example there are two columns and three rows.
The first column is fixed at 150px.
The second column uses flexible sizing, which is a function of the unassigned space in the grid,
and thus will vary as the width of the <a>grid container</a> changes.
If the used width of the <a>grid container</a> is 200px, then the second column is 50px wide.
If the used width of the <a>grid container</a> is 100px, then the second column is 0px
and any content positioned in the column will overflow the <a>grid container</a>.
<pre>
#grid {
display: grid;
grid-template-columns: 150px 1fr; /* two columns */
grid-template-rows: 50px 1fr 50px; /* three rows */
}
</pre>
</div>
<h3 id="grid-area-concept">
Grid Areas</h3>
A <dfn export>grid area</dfn> is the logical space used to lay out one or more <a>grid items</a>.
A <a>grid area</a> consists of one or more adjacent <a>grid cells</a>.
It is bound by four <a>grid lines</a>, one on each side of the <a>grid area</a>,
and participates in the sizing of the <a>grid tracks</a> it intersects.
A <a>grid area</a> can be named explicitly using the 'grid-template-areas' property of the <a>grid container</a>,
or referenced implicitly by its bounding <a>grid lines</a>.
A <a>grid item</a> is assigned to a <a>grid area</a>
using the <a href="#placement">grid-placement properties</a>.
<div class="example">
<pre>
/* using the template syntax */
#grid {
display: grid;
grid-template-areas: ". a"
"b a"
". a";
grid-template-columns: 150px 1fr;
grid-template-rows: 50px 1fr 50px;
}
#item1 { grid-area: a }
#item2 { grid-area: b }
#item3 { grid-area: b }
/* Align items 2 and 3 at different points in the grid area "b". */
/* By default, grid items are stretched to fit their grid area */
/* and these items would layer one over the other. */
#item2 { align-self: start; }
#item3 { justify-self: end; align-self: end; }
</pre>
</div>
A <a>grid item</a>’s <a>grid area</a> forms the containing block into which it is laid out.
<a>Grid items</a> placed into the same <a>grid area</a> do not directly affect each other's layout.
Indirectly, however, a <a>grid item</a> occupying a <a>grid track</a> with an <a>intrinsic sizing function</a>
can affect the size of that track (and thus the positions of its bounding <a>grid lines</a>),
which in turn can affect the position or size of another <a>grid item</a>.
<h2 id="order-accessibility">
Reordering and Accessibility</h2>
Grid layout gives authors great powers of rearrangement over the document.
However, these are not a substitute for correct ordering of the document source.
The 'order' property and <a>grid placement</a>
<em>do not</em> affect ordering in non-visual media
(such as <a href="https://www.w3.org/TR/css3-speech/">speech</a>).
Likewise, rearranging grid items visually does not affect
the default traversal order of sequential navigation modes
(such as cycling through links, see e.g. <a href="https://www.w3.org/TR/html5/editing.html#sequential-focus-navigation-and-the-tabindex-attribute"><code>tabindex</code></a> [[HTML5]]).
Advisement:
Authors <em>must</em> use 'order' and the <a>grid-placement properties</a>
only for visual, not logical, reordering of content.
Style sheets that use these features to perform logical reordering are non-conforming.
Note: This is so that non-visual media and non-CSS UAs,
which typically present content linearly,
can rely on a logical source order,
while grid layout’s placement and ordering features are used to tailor the visual arrangement.
(Since visual perception is two-dimensional and non-linear,
the desired visual order is not always equivalent to the desired reading order.)
<div class='example'>
Many web pages have a similar shape in the markup,
with a header on top,
a footer on bottom,
and then a content area and one or two additional columns in the middle.
Generally,
it's desirable that the content come first in the page's source code,
before the additional columns.
However, this makes many common designs,
such as simply having the additional columns on the left and the content area on the right,
difficult to achieve.
This has been addressed in many ways over the years,
often going by the name "Holy Grail Layout" when there are two additional columns.
Grid Layout makes this example trivial.
For example, take the following sketch of a page's code and desired layout:
<div class='code-and-figure'>
<div>
<pre class="lang-markup">
<!DOCTYPE html>
<header>...</header>
<article>...</article>
<nav>...</nav>
<aside>...</aside>
<footer>...</footer>
</pre>
</div>
<div><img src="images/grid-order-page.svg" width=400 height=360 alt="In this page the header is at the top and the footer at the bottom, but the article is in the center, flanked by the nav on the right and the aside on the left."></div>
</div>
This layout can be easily achieved with grid layout:
<pre class="lang-css">
main { display: grid;
grid: "h h h"
"a b c"
7ED6
"f f f";
grid-template-columns: auto 1fr 20%; }
article { grid-area: b; min-width: 12em; }
nav { grid-area: a; /* auto min-width */ }
aside { grid-area: c; min-width: 12em; }
</pre>
As an added bonus,
the columns will all be <a value for="align-self" lt="stretch">equal-height</a> by default,
and the main content will be as wide as necessary to fill the screen.
Additionally,
this can then be combined with media queries to switch to an all-vertical layout on narrow screens:
<pre class="lang-css">
@media all and (max-width: 60em) {
/* Too narrow to support three columns */
main { display: block; }
}
</pre>
</div>
In order to preserve the author's intended ordering in all presentation modes,
authoring tools—including WYSIWYG editors as well as Web-based authoring aids--
must reorder the underlying document source
and not use 'order' or <a>grid-placement properties</a> to perform reordering
unless the author has explicitly indicated that the underlying
document order (which determines speech and navigation order) should be
<em>out-of-sync</em> with the visual order.
<div class="example">
For example, a tool might offer both drag-and-drop arrangement of grid items
as well as handling of media queries for alternate layouts per screen size range.
Since most of the time, reordering should affect all screen ranges
as well as navigation and speech order,
the tool would match the resulting drag-and-drop visual arrangement
by simultaneously reordering the DOM layer.
In some cases, however, the author may want different visual arrangements per screen size.
The tool could offer this functionality
by using the <a>grid-placement properties</a> together with media queries,
but also tie the smallest screen size's arrangement to the underlying DOM order
(since this is most likely to be a logical linear presentation order)
while using <a>grid-placement properties</a>
to rearrange the visual presentation in other size ranges.
This tool would be conformant, whereas a tool that only ever used
the <a>grid-placement properties</a>
to handle drag-and-drop grid rearrangement
(however convenient it might be to implement it that way)
would be non-conformant.
</div>
<!--
████████ ████ ██████ ████████ ██ ███ ██ ██ ██ ██████ ████████ ████ ████████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██████ ████████ ██ ██ ██ ██ ██ ████ ████████ ██ ██ ██
██ ██ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██
████████ ████ ██████ ██ ████████ ██ ██ ██ ██ ██████ ██ ██ ████ ████████
-->
<h2 id="grid-model">
Grid Containers</h2>
<h3 id='grid-containers'>
Establishing Grid Containers: the ''display/grid'' and ''inline-grid'' 'display' values</h3>
<pre class="propdef">
Name: display
New values: grid | inline-grid
</pre>
<dl dfn-for="display" dfn-type=value>
<dt><dfn>grid</dfn>
<dd>
This value causes an element to generate a block-level <a>grid container</a> box.
<dt><dfn>inline-grid</dfn>
<dd>
This value causes an element to generate an inline-level <a>grid container</a> box.
</dl>
A <dfn export>grid container</dfn> establishes a new <dfn export>grid formatting context</dfn> for its contents.
This is the same as establishing a block formatting context,
except that grid layout is used instead of block layout:
floats do not intrude into the grid container,
and the grid container's margins do not collapse with the margins of its contents.
The contents of a <a>grid container</a> are laid out into a <a>grid</a>,
with <a>grid lines</a> forming the boundaries of each <a>grid items</a>’ containing block.
The 'overflow' property applies to <a>grid containers</a>.
Grid containers are not block containers,
and so some properties that were designed with the assumption of block layout
don't apply in the context of grid layout.
In particular:
<ul>
<li>
'float' and 'clear' have no effect on a <a>grid item</a>.
However, the 'float' property still affects the computed value of 'display' on children of a grid container,
as this occurs <em>before</em> <a>grid items</a> are determined.
<li>
'vertical-align' has no effect on a grid item.
<li>
the ''::first-line'' and ''::first-letter'' pseudo-elements do not apply to <a>grid containers</a>,
and <a>grid containers</a> do not contribute a first formatted line or first letter to their ancestors.
</ul>
If an element's specified 'display' is ''inline-grid''
and the element is floated or absolutely positioned,
the computed value of 'display' is <a value>grid</a>.
The table in <a href="https://www.w3.org/TR/CSS2/visuren.html#dis-pos-flo">CSS 2.1 Chapter 9.7</a> is thus amended
to contain an additional row,
with ''inline-grid'' in the "Specified Value" column
and ''grid'' in the "Computed Value" column.
<h3 id='intrinsic-sizes'>
Sizing Grid Containers</h3>
Note see [[!CSS3-SIZING]] for a definition of the terms in this section.
A <a>grid container</a> is sized
using the rules of the formatting context in which it participates:
<ul>
<li>
As a <a>block-level</a> box in a <a>block formatting context</a>,
it is sized like a <a>block box</a> that establishes a formatting context,
with an ''auto'' <a>inline size</a> calculated as for non-replaced block boxes.
<li>
As an inline-level box in an <a>inline formatting context</a>,
it is sized as an atomic inline-level box (such as an inline-block).
</ul>
In both inline and block formatting contexts,
the <a>grid container</a>’s ''auto'' <a>block size</a> is its max-content size.
<span class="note">The block layout spec should probably define this,
but it isn't written yet.</span>
The <a>max-content size</a> (<a>min-content size</a>) of a <a>grid container</a> is
the sum of the <a>grid container’s</a> track sizes (including gutters)
in the appropriate axis,
when the grid is sized under a <a>max-content constraint</a> (<a>min-content constraint</a>).
<!--
██████ ██ ███ ██ ██ ████████ ████ ██ ██ ██████
██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ███ ██ ██ ██
██ ██ ██ ██ ████ ████ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ██ ███ ██ ████████ ██ ██ ██ ██ ██ ████
██ ██ █████████ ██ ██ ██ ██ ██ ████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██
██████ ████████ ██ ██ ██ ██ ██ ████ ██ ██ ██████
-->
<h3 id="overlarge-grids">
Clamping Overly Large Grids</h3>
Since memory is limited,
UAs may clamp the possible size of the <a>grid</a>
to be within a UA-defined limit,
dropping all lines outside that limit.
If a grid item is placed outside this limit,
its grid area must be <a>clamped</a> to within this limited grid.
To <dfn local-lt=clamp>clamp a grid area</dfn>:
* If the <a>grid area</a> would <a>span</a> outside the limited grid,
its span is clamped to the last line of the limited <a>grid</a>.
* If the <a>grid area</a> would be placed completely outside the limited grid,
its span must be truncated to 1
and the area repositioned into the last <a>grid track</a> on that side of the grid.
<div class='example'>
For example, if a UA only supported grids with at most 1000 tracks in each dimension,
the following placement properties:
<pre class="lang-css">
.grid-item {
grid-row: 500 / 1500;
grid-column: 2000 / 3000;
}
</pre>
Would end up being equivalent to:
<pre class="lang-css">
.grid-item {
grid-row: 500 / 1001;
grid-column: 1000 / 1001;
}
</pre>
</div>
<!--
██████ ████████ ████ ████████ ████ ████████ ████████ ██ ██ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ████ ██
██ ████ ████████ ██ ██ ██ ██ ██ ██████ ██ ███ ██ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ██ ██ ████ ████████ ████ ██ ████████ ██ ██ ██████
-->
<h2 id="grid-items">
Grid Items</h2>
Loosely speaking, the <dfn export id="grid-item" lt="grid item">grid items</dfn> of a <a>grid container</a>
are boxes representing its in-flow contents.
Each in-flow child of a <a>grid container</a>
becomes a <a>grid item</a>,
and each contiguous sequence of child <a>text runs</a>
is wrapped in an <a>anonymous</a> <a>block container</a> <a>grid item</a>.
However, if the entire sequence of child <a>text runs</a> contains only
<a href="https://www.w3.org/TR/CSS2/text.html#white-space-prop">white space</a>
(i.e. characters that can be affected by the 'white-space' property)
it is instead not rendered (just as if its <a>text nodes</a> were ''display:none'').
<div class="example">
<p>Examples of grid items:
<pre class="lang-markup">
<div style="display: grid">
<!-- grid item: block child -->
<div id="item1">block</div>
<!-- grid item: floated element; floating is ignored -->
<div id="item2" style="float: left;">float</div>
<!-- grid item: anonymous block box around inline content -->
anonymous item 3