csswg-drafts/css2/tables.src at 94982e838a558e6c66516b3b13e403eae32e27ad · w3c/csswg-drafts · GitHub

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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html 
4B9A
lang="en">
<!-- $Id: tables.src,v 2.134 2014-01-17 13:45:10 bbos Exp $ -->
<head>
<title>Tables</title>
<!--script src="http://www.w3c-test.org/css/harness/annotate.js#CSS21_DEV" type="text/javascript" defer></script-->
</head>
<body>
<h1>Tables</h1>
<h2><a name="tables-intro">Introduction to tables</a></h2>

<p>This chapter defines the processing model for tables in CSS. Part
of this processing model is the layout. For the layout, this chapter
introduces two algorithms; the first, the fixed table layout
algorithm, is well-defined, but the second, the automatic table layout
algorithm, is not fully defined by this specification.

<p>For the automatic table layout algorithm, some widely deployed
implementations have achieved relatively close interoperability.

<p><span class="index-def" title="tables">Table</span> layout can be
used to represent tabular relationships between data. Authors specify
these relationships in the <a href="conform.html#doclanguage">document
language</a> and can specify their <em>presentation</em> using
CSS&nbsp;2.1.

<p>In a visual medium, CSS tables can also be used to achieve specific
layouts. In this case, authors should not use table-related elements
in the document language, but should apply the CSS to the relevant
structural elements to achieve the desired layout.

<p>Authors may specify the visual formatting of a table as a
rectangular grid of cells. Rows and columns of cells may be organized
into row groups and column groups. Rows, columns, row groups, column
groups, and cells may have borders drawn around them (there are two
border models in CSS&nbsp;2.1). Authors may align data vertically or
horizontally within a cell and align data in all cells of a row or
column.

<div class="example"><p>
Here is a simple three-row, three-column
table described in HTML 4:

<pre class="html-example">
&lt;TABLE&gt;
&lt;CAPTION&gt;This is a simple 3x3 table&lt;/CAPTION&gt;
&lt;TR id="row1"&gt;
   &lt;TH&gt;Header 1  &lt;TD&gt;Cell 1  &lt;TD&gt;Cell 2
&lt;TR id="row2"&gt;
   &lt;TH&gt;Header 2  &lt;TD&gt;Cell 3  &lt;TD&gt;Cell 4
&lt;TR id="row3"&gt;
   &lt;TH&gt;Header 3  &lt;TD&gt;Cell 5  &lt;TD&gt;Cell 6
&lt;/TABLE&gt;
</pre>

<p>This code creates one table (the TABLE element), three
rows (the TR elements), three header cells (the TH elements),
and six data cells (the TD elements). Note that the three columns
of this example are specified implicitly: there are as many
columns in the table as required by header and data cells.

<p>The following CSS rule centers the text horizontally in the header
cells and presents the text in the header cells with a bold font
weight:

<pre>
th { text-align: center; font-weight: bold }
</pre>

<p>The next rules align the text of the header cells on their baseline
and vertically center the text in each data cell:

<pre>
th { vertical-align: baseline }
td { vertical-align: middle }
</pre>

<p>The next rules specify that the top row will be surrounded by a 3px
solid blue border and each of the other rows will be surrounded by a
1px solid black border:

<pre>
table   { border-collapse: collapse }
tr#row1 { border: 3px solid blue }
tr#row2 { border: 1px solid black }
tr#row3 { border: 1px solid black }
</pre>

<p>Note, however, that the borders around the rows overlap where the
rows meet. What color (black or blue) and thickness (1px or 3px) will
the border between row1 and row2 be? We discuss this in the section on
<a href="#border-conflict-resolution">border conflict resolution.</a>

<p>The following rule puts the table caption above the table:

<pre>
caption { caption-side: top }
</pre>

</div>

<p>The preceding example shows how CSS works with HTML 4 elements;
in HTML 4, the semantics of the various table elements (TABLE,
CAPTION, THEAD, TBODY, TFOOT, COL, COLGROUP, TH, and TD) are
well-defined. In other document languages (such as XML applications),
there may not be pre-defined table elements. Therefore, CSS&nbsp;2.1 allows
authors to <span class="index-inst" title="mapping elements to table
parts">"map"</span> document language elements to table elements via
the <span class="propinst-display">'display'</span> property. For
example, the following rule makes the FOO element act like an HTML
TABLE element and the BAR element act like a CAPTION element:</p>

<PRE class="example">
FOO { display : table }
BAR { display : table-caption }
</pre>

<p><a name="internal"></a> We discuss the various table elements in the
following section. In
this specification, the term <span class="index-def" title="table
element"><dfn>table element</dfn></span> refers to any element
involved in the creation of a table. An <span class="index-def"
title="internal table element|table element::internal"><dfn id="internal-table-element">internal
table element</dfn></span> is one that produces a row, row group, column,
column group, or cell.

<h2><a name="table-display">The CSS table model</a></h2>

<p>The CSS table model is based on the HTML4 table model, in
which the structure of a table closely parallels the visual layout of
the table. In this model, a table consists of an optional caption and
any number of rows of cells. The table model is said to be "row
primary" since authors specify rows, not columns, explicitly in the
document language. Columns are derived once all the rows have been
specified -- the first cell of each row belongs to the first column,
the second to the second column, etc.). Rows and columns may be
grouped structurally and this grouping reflected in presentation
(e.g., a border may be drawn around a group of rows).

<p>Thus, the table model consists of tables, captions, rows, <span
class=index-def>row groups</span> (including header groups and footer
groups), columns, column groups, and cells.

<p>The CSS model does not require that the <a
href="conform.html#doclanguage">document language</a> include elements
that correspond to each of these components.  For document languages
(such as XML applications) that do not have pre-defined table
elements, authors must map document language elements to table
elements; this is done with the <span
class="propinst-display">'display'</span> property. The following
<span class="propinst-display">'display'</span> values assign table
formatting rules to an arbitrary element:

<dl>
  <dt><strong><span class="index-def" title="table"><a
  class="value-def" name="value-def-table">table</a></span></strong>
  (In HTML: TABLE) <dd>Specifies that an element defines a <a
  href="visuren.html#block-level">block-level</a> table: it is a
  rectangular block that participates in a <a
  href="visuren.html#block-formatting">block formatting context</a>.

  <dt><strong><span class="index-def" title="inline-table"><a
  class="value-def"
  name="value-def-inline-table">inline-table</a></span></strong> (In
  HTML: TABLE) <dd>Specifies that an element defines an <a
  href="visuren.html#inline-level">inline-level</a> table: it is a
  rectangular block that participates in an <a
  href="visuren.html#inline-formatting">inline formatting
  context</a>).

  <dt><strong><span class="index-def" title="table-row"><a
  class="value-def"
  name="value-def-table-row">table-row</a></span></strong> (In HTML:
  TR) <dd>Specifies that an element is a row of cells.

  <dt><strong><span class="index-def" title="table-row-group"><a
  class="value-def"
  name="value-def-table-row-group">table-row-group</a></span></strong>
  (In HTML: TBODY) <dd>Specifies that an element groups one or more
  rows.

  <dt><strong><span class="index-def" title="table-header-group"><a
  class="value-def"
  name="value-def-table-header-group">table-header-group</a></span></strong>
  (In HTML: THEAD) <dd>Like 'table-row-group', but for visual
  formatting, the row group is always displayed before all other rows
  and row groups and after any top captions. Print user agents may
  repeat header rows on each page spanned by a table. If a table
  contains multiple elements with 'display: table-header-group', only
  the first is rendered as a header; the others are treated as if they
  had 'display: table-row-group'.

  <dt><strong><span class="index-def" title="table-footer-group"><a
  class="value-def"
  name="value-def-table-footer-group">table-footer-group</a></span></strong>
  (In HTML: TFOOT) <dd>Like 'table-row-group', but for visual
  formatting, the row group is always displayed after all other rows
  and row groups and before any bottom captions. Print user agents may
  repeat footer rows on each page spanned by a table. If a table
  contains multiple elements with 'display: table-footer-group', only
  the first is rendered as a footer; the others are treated as if they
  had 'display: table-row-group'.

  <dt><strong><span class="index-def" title="table-column"><a
  class="value-def"
  name="value-def-table-column">table-column</a></span></strong> (In
  HTML: COL) <dd>Specifies that an element describes a column of
  cells.

  <dt><strong><span class="index-def" title="table-column-group"><a
  class="value-def"
  name="value-def-table-column-group">table-column-group</a></span></strong>
  (In HTML: COLGROUP) <dd>Specifies that an element groups one or more
  columns.

  <dt><strong><span class="index-def" title="table-cell"><a
  class="value-def"
  name="value-def-table-cell">table-cell</a></span></strong> (In HTML:
  TD, TH) <dd>Specifies that an element represents a table cell.

  <dt><strong><span class="index-def" title="table-caption"><a
  class="value-def"
  name="value-def-table-caption">table-caption</a></span></strong> (In
  HTML: CAPTION) <dd>Specifies a caption for the table. All elements
  with 'display: table-caption' must be rendered, as described in
  <a href="#model">section 17.4.</a>
</dl>

<p>Replaced elements with these <span
class="propinst-display">'display'</span> values are treated as their
given display types during layout. For example, an image that is set
to 'display: table-cell' will fill the available cell space, and its
dimensions might contribute towards the table sizing algorithms, as
with an ordinary cell.

<p>Elements with <span class="propinst-display">'display'</span> set
to 'table-column' or 'table-column-group' are not rendered (exactly as
if they had 'display: none'), but they are useful, because they may
have attributes which induce a certain style for the columns they
represent.

<p>The <a href="sample.html">default style sheet for HTML4</a>
in the appendix illustrates the use of these values for HTML4:

<pre class="example">
table    { display: table }
tr       { display: table-row }
thead    { display: table-header-group }
tbody    { display: table-row-group }
tfoot    { display: table-footer-group }
col      { display: table-column }
colgroup { display: table-column-group }
td, th   { display: table-cell }
</pre>

<p>User agents may <a href="syndata.html#ignore">ignore</a> these
<span class="propinst-display">'display'</span> property values for
HTML table elements, since HTML tables may be rendered using other
algorithms intended for backwards compatible rendering. However, this
is not meant to discourage the use of 'display: table' on other,
non-table elements in HTML.

<h3><a name="anonymous-boxes">Anonymous table objects</a></h3>

<p>Document languages other than HTML may not contain all the elements
in the CSS&nbsp;2.1 table model. In these cases, the "missing"
elements must be assumed in order for the table model to work. Any
table element will automatically generate necessary anonymous table
objects around itself, consisting of at least three nested objects
corresponding to a 'table'/'inline-table' element, a 'table-row'
element, and a 'table-cell' element. Missing elements generate <a
href="visuren.html#anonymous">anonymous</a> objects (e.g., anonymous
boxes in visual table layout) according to the following rules:

<p>For the purposes of these rules, the following terms are defined:
<dl>
  <dt><span class="index-def">row group box</span>
    <dd>A 'table-row-group', 'table-header-group', or
    'table-footer-group'

  <dt><span class="index-def">proper table child</span>
    <dd>A 'table-row' box, row group box, 'table-column' box,
    'table-column-group' box, or 'table-caption' box.

  <dt><span class="index-def">proper table row parent</span>
    <dd>A 'table' or 'inline-table' box or row group box

  <dt><span class="index-def">internal table box</span>
    <dd>A 'table-cell' box, 'table-row' box, row group box,
    'table-column' box, or 'table-column-group' box.

  <dt id="tabular-container"><span class="index-def">tabular container</span>
    <dd>A 'table-row' box or proper table row parent

  <dt><span class="index-def">consecutive</span>
    <dd>Two sibling boxes are consecutive if they have no intervening
    siblings other than, optionally, an anonymous inline containing
    only white spaces. A sequence of sibling boxes is consecutive if
    each box in the sequence is consecutive to the one before it in
    the sequence.
</dl>
<p>For the purposes of these rules, out-of-flow elements are
represented as inline elements of zero width and height. Their
containing blocks are chosen accordingly.

<p>The following steps are performed in three stages.
<ol>
  <li>Remove irrelevant boxes:
    <ol>
      <li>All child boxes of a 'table-column' parent are treated as if
          they had 'display: none'.

      <li>If a child <var>C</var> of a 'table-column-group' parent is
          not a 'table-column' box, then it is treated as if it had
          'display: none'.

      <li>If a child <var>C</var> of a tabular container <var>P</var>
          is an anonymous inline box that contains only white space,
          and its immediately preceding and following siblings, if
          any, are proper table descendants of <var>P</var> and are
          either 'table-caption' or internal table boxes, then it is
          trea
7484
ted as if it had 'display: none'. A box <var>D</var> is
          a proper table descendant of <var>A</var> if <var>D</var>
          can be a descendant of <var>A</var> without causing the
          generation of any intervening 'table' or 'inline-table'
          boxes.

      <li>If a box <var>B</var> is an anonymous inline containing only
          white space, and is between two immediate siblings each of
          which is either an internal table box or a 'table-caption'
          box then <var>B</var> is treated as if it had 'display:
          none'.
    </ol>

  <li>Generate missing child wrappers:
    <ol>
      <li>If a child <var>C</var> of a 'table' or 'inline-table' box
          is not a proper table child, then generate an anonymous
          'table-row' box around <var>C</var> and all consecutive
          siblings of <var>C</var> that are not proper table children.

      <li>If a child <var>C</var> of a row group box is not a
          'table-row' box, then generate an anonymous 'table-row' box
          around <var>C</var> and all consecutive siblings
          of <var>C</var> that are not 'table-row' boxes.

      <li>If a child <var>C</var> of a 'table-row' box is not a
          'table-cell', then generate an anonymous 'table-cell' box
          around <var>C</var> and all consecutive siblings
          of <var>C</var> that are not 'table-cell' boxes.
    </ol>

  <li>Generate missing parents:
    <ol>
       <li>For each 'table-cell' box <var>C</var> in a sequence of
           consecutive internal table and 'table-caption' siblings,
           if <var>C</var>'s parent is not a 'table-row' then generate
           an anonymous 'table-row' box around <var>C</var> and all
           consecutive siblings of <var>C</var> that are 'table-cell'
           boxes.

       <li>For each proper table child <var>C</var> in a sequence of
           consecutive proper table children, if <var>C</var> is
           misparented then generate an anonymous 'table' or
           'inline-table' box <var>T</var> around <var>C</var> and all
           consecutive siblings of <var>C</var> that are proper table
           children. (If C's parent is an 'inline' box,
           then <var>T</var> must be an 'inline-table' box; otherwise
           it must be a 'table' box.)
           <ul>
             <li>A 'table-row' is misparented if its parent is neither
               a row group box nor a 'table' or 'inline-table' box.
             <li>A 'table-column' box is misparented if its parent is
               neither a 'table-column-group' box nor a 'table' or
               'inline-table' box.
             <li>A row group box, 'table-column-group' box, or
               'table-caption' box is misparented if its parent is
               neither a 'table' box nor an 'inline-table' box.
           </ul>
    </ol>
</ol>

<div class="example">
<p>In this XML example, a 'table' element is assumed to contain the
HBOX element:

<pre class="xml-example">
&lt;HBOX&gt;
  &lt;VBOX&gt;George&lt;/VBOX&gt;
  &lt;VBOX&gt;4287&lt;/VBOX&gt;
  &lt;VBOX&gt;1998&lt;/VBOX&gt;
&lt;/HBOX&gt;
</pre>

<p>because the associated style sheet is:

<pre class="example">
HBOX { display: table-row }
VBOX { display: table-cell }
</pre>
</div>

<div class="example">
<p>In this example, three 'table-cell' elements are assumed to contain
the text in the ROWs. Note that the text is further encapsulated in
anonymous inline boxes, as explained in <a
href="visuren.html#anonymous">visual formatting model</a>:

<pre class="xml-example">
&lt;STACK&gt;
  &lt;ROW&gt;This is the &lt;D&gt;top&lt;/D&gt; row.&lt;/ROW&gt;
  &lt;ROW&gt;This is the &lt;D&gt;middle&lt;/D&gt; row.&lt;/ROW&gt;
  &lt;ROW&gt;This is the &lt;D&gt;bottom&lt;/D&gt; row.&lt;/ROW&gt;
&lt;/STACK&gt;
</pre>

<p>The style sheet is:

<pre class="example">
STACK { display: inline-table }
ROW   { display: table-row }
D     { display: inline; font-weight: bolder }
</pre>
</div>

<h2><a name="columns">Columns</a></h2>

<p>Table cells may belong to two contexts: rows and columns. However,
in the source document cells are descendants of rows, never of
columns. Nevertheless, some aspects of cells can be influenced by
setting properties on columns.

<p>The following properties apply to column and column-group elements:

<dl>
  <dt><span class="propinst-border">'border'</span>

    <dd>The various border properties apply to columns only if <span
    class="propinst-border-collapse">'border-collapse'</span> is set
    to 'collapse' on the table element. In that case, borders set on
    columns and column groups are input to the <a
    href="#border-conflict-resolution">conflict resolution
    algorithm</a> that selects the border styles at every cell edge.

  <dt><span class="propinst-background">'background'</span>

    <dd>The background properties set the background for cells in the
    column, but only if both the cell and row have transparent
    backgrounds. See <a href="#table-layers">"Table layers and
    transparency."</a>

  <dt><span class="propinst-width">'width'</span>

    <dd>The <span class="propinst-width">'width'</span> property gives
    the minimum width for the column.

  <dt><span class="propinst-visibility">'visibility'</span>

    <dd>If the 'visibility' of a column is set to 'collapse', none of
    the cells in the column are rendered, and cells that span into
    other columns are clipped. In addition, the width of the table is
    diminished by the width the column would have taken up. See <a
    href="#dynamic-effects">"Dynamic effects"</a> below. Other values
    for 'visibility' have no effect.
</dl>

<div class="example">
<p>Here are some examples of style rules that set properties on
columns. The first two rules together implement the "rules" attribute
of HTML 4 with a value of "cols". The third rule makes the "totals"
column blue, the final two rules shows how to make a column a fixed
size, by using the <a href="#fixed-table-layout">fixed layout
algorithm</a>.

<pre>
col { border-style: none solid }
table { border-style: hidden }
col.totals { background: blue }
table { table-layout: fixed }
col.totals { width: 5em }
</pre>
</div>

<h2><a name="model">Tables in the visual formatting model</a></h2>

<p>In terms of the visual formatting model, a table can behave like a
<a href="visuren.html#block-level">block-level</a> (for 'display:
table') or <a href="visuren.html#inline-level">inline-level</a> (for
'display: inline-table') element.

<p>In both cases, the table generates a principal block box called the
<dfn>table wrapper box</dfn> that
contains the table box itself and any caption boxes (in document
order).
The <dfn>table box</dfn> is a block-level box that contains the
table's internal table boxes.
The caption boxes are block-level boxes that retain their own
content, padding, margin, and border areas, and are rendered as normal
block boxes inside the table wrapper box. Whether the caption boxes are placed
before or after the table box is decided by the 'caption-side'
property, as described below.

<p>The table wrapper box is a 'block' box if the table is block-level, and
an 'inline-block' box if the table is inline-level. The table wrapper box
establishes a block formatting context. The table box (not the
table wrapper box) is used when doing baseline
vertical alignment for an 'inline-table'. The width of the table wrapper
box is the border-edge width of the table box inside it, as described
by section 17.5.2. Percentages on 'width' and 'height' on the table are
relative to the table wrapper box's containing block, not the table wrapper box
itself.

<p>The computed values of properties 'position', 'float', 'margin-*',
'top', 'right', 'bottom', and 'left' on the table element are used on
the table wrapper box and not the table box; all other values of
non-inheritable properties are used on the table box and not the table
wrapper box. (Where the table element's values are not used on the
table and table wrapper boxes, the initial values are used instead.)

<div class="figure">
<p><img src="images/table_container.png" alt="A table with a caption above
it">

<p class="caption">Diagram of a table with a caption above it.
</div>

<h3><a name="caption-position">Caption position and alignment</a></h3>

<!-- #include src=properties/caption-side.srb -->

<p>This property specifies the position of the caption box with
respect to the table box. Values have the following meanings:

<dl>
  <dt><strong>top</strong> <dd>Positions the caption box above the
  table box.

  <dt><strong>bottom</strong> <dd>Positions the caption box below the
  table box.
</dl>

<div class=note>
<p><em><strong>Note:</strong> CSS2 described a different width and
horizontal alignment behavior. That behavior will be introduced in
CSS3 using the values 'top-outside' and 'bottom-outside' on this
property.</em>
</div>

<p>To align caption content horizontally within the caption box, use
the <span class="propinst-text-align">'text-align'</span> property.

<div class="example">
<p>In this example, the <span
class="propinst-caption-side">'caption-side'</span> property places
captions below tables.  The caption will be as wide as the parent of
the table, and caption text will be left-justified.

<pre>
caption { caption-side: bottom;
          width: auto;
          text-align: left }
</pre>
</div>

<h2><a name="table-layout">Visual layout of table contents</a></h2>

<p>Internal table elements generate rectangular <a
href="box.html#box-dimensions">boxes</a> with content and borders.
Cells have padding as well. Internal table elements do not have
margins.

<p>The visual layout of these boxes is governed by a rectangular,
irregular grid of rows and columns. Each box occupies a whole number
of grid cells, determined according to the following rules. These
rules do not apply to HTML 4 or earlier HTML versions; HTML imposes
its own limitations on row and column spans.

<ol>
  <li>Each row box occupies one row of grid cells. Together, the row
  boxes fill the table from top to bottom in the order they occur in
  the source document (i.e., the table occupies exactly as many grid
  rows as there are row elements).

  <li>A row group occupies the same grid cells as the rows it
  contains.

  <li>A column box occupies one or more columns of grid cells. Column
  boxes are placed next to each other in the order they occur. The
  first column box may be either on the left or on the right,
  depending on the value of the <span
  class="propinst-direction">'direction'</span> property of the table.

  <li>A column group box occupies the same grid cells as the columns
  it contains.

  <li>Cells may span several rows or columns. (Although CSS&nbsp;2.1
  does not define how the number of spanned rows or columns is
  determined, a user agent may have special knowledge about the source
  document; a future update of CSS may provide a way to express this
  knowledge in CSS syntax.) Each cell is thus a rectangular box, one
  or more grid cells wide and high. The top row of this rectangle is
  in the row specified by the cell's parent. The rectangle must be as
  far to the left as possible, but the part of the cell in the first
  column it occupies must not overlap with any other cell box (i.e., a
  row-spanning cell starting in a prior row), and the cell must be to
  the right of all cells in the same row that are earlier in the
  source document. If this position would cause a column-spanning cell
  to overlap a row-spanning cell from a prior row, CSS does not define
  the results: implementations may either overlap the cells (as is
  done in many HTML implementations) or may shift the later cell to
  the right to avoid such overlap. (This constraint holds if the
  'direction' property of the table is 'ltr'; if the 'direction' is
  'rtl', interchange "left" and "right" in the previous two
  sentences.)

  <li>A cell box cannot extend beyond the last row box of a table or
  row group; the user agents must shorten it until it fits.
</ol>

<p>The edges of the rows, columns, row groups and column groups in the
<a href="#collapsing-borders">collapsing borders model</a> coincide
with the hypothetical grid lines on which the borders of the cells are
centered. (And thus, in this model, the rows together exactly cover
the table, leaving no gaps; ditto for the columns.) In the <a
href="#separated-borders">separated borders model,</a> the edges
coincide with the <a href="box.html#border-edge">border edges</a> of
cells. (And thus, in this model, there may be gaps between the rows,
columns, row groups or column groups, corresponding to the <span
class="propinst-border-spacing">'border-spacing'</span> property.)

<div class="note">
<p><em><strong>Note.</strong> Positioning and floating of table cells
can cause them not to be table cells anymore, according to the rules
in <a href="visuren.html#dis-pos-flo">section 9.7</a>. When floating
is used, the <a>rules on anonymous table objects</a> may cause an
anonymous cell object to be created as well.</em>
</div>

<div class="html-example">
<p>Here is an example illustrating rule 5. The following illegal
  (X)HTML snippet defines conflicting cells:

<pre>
&lt;table&gt;
&lt;tr&gt;&lt;td&gt;1 &lt;/td&gt;&lt;td rowspan="2"&gt;2 &lt;/td&gt;&lt;td&gt;3 &lt;/td&gt;&lt;td&gt;4 &lt;/td&gt;&lt;/tr&gt;
&lt;tr&gt;&lt;td colspan="2"&gt;5 &lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;
</pre>

<p>User agents are free to visually overlap the cells, as in the
figure on the left, or to shift the cell to avoid the visual
overlap, as in the figure on the right.

<div class="figure">
<p><img src="images/table-overlap.png" alt="One table with overlapping
cells and one without"> <p class="caption">Two possible
renderings of an erroneous HTML table.
</div>
</div>

<h3><a name="table-layers">Table layers and transparency</a></h3>

<p>For the purposes of finding the background of each table cell, the
different table elements may be thought of as being on six
superimposed layers. The background set on an element in one of the
layers will only be visible if the layers above it have a transparent
background.

<div class="figure">
<p><img src="images/tbl-layers.png" alt="schema of table layers">

<p class="caption">Schema of table layers.
</div>

<ol>
  <li>The lowest layer is a single plane, representing the table box
  itself. Like all boxes, it may be transparent.

  <li>The next layer contains the column groups. Each column group
  extends from the top of the cells in the top row to the bottom of
  the cells on the bottom row and from the left edge of its leftmost
  column to the right edge of its rightmost column. The background
  covers exactly the full area of all cells that originate in the
  difference in area does not affect background image positioning.

  <li>On top of the column groups are the areas representing the
  column boxes. Each column is as tall as the column groups and as
  wide as a normal (single-column-spanning) cell in the column. The
  background covers exactly the full area of all cells that originate
  in the column, even if they span outside the column, but this
  difference in area does not affect background image positioning.

  <li>Next is the layer containing the row groups. Each row group
  extends from the top left corner of its topmost cell in the first
  column to the bottom right corner of its bottommost cell in the last
  column.

  <li>The next to last layer contains the rows. Each row is as wide as
  the row groups and as tall as a normal (single-row-spanning) cell in
  the row. As with columns, the background covers exactly the full
  area of all cells that originate in the row, even if they span
  outside the row, but this difference in area does not affect
  background image positioning.

  <li>The topmost layer contains the cells themselves. As the figure
  shows, although all rows contain the same number of cells, not every
  cell may have specified content.
  In the <a href="#separated-borders">separated borders model</a>
  (<span class="propinst-border-collapse">'border-collapse'</span> is
  'separate'), if the value of their <span
  class="propinst-empty-cells">'empty-cells'</span> property is 'hide'
  these "empty" cells are transparent through the cell, row, row
  group, column and column group backgrounds, letting the table
  background show through.
</ol>

<p>A "missing cell" is a cell in the row/column grid that is not
occupied by an element or pseudo-element. Missing cells are rendered
as if an anonymous table-cell box occupied their position in the grid.

<div class="html-example">
<p>In the following example, the first row contains four non-empty
cells, but the second row contains only one non-empty cell, and thus
the table background shines through, except where a cell from the
first row spans into this row. The following HTML code and style rules

<pre>
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"&gt;
&lt;HTML&gt;
  &lt;HEAD&gt;
    &lt;TITLE&gt;Table example&lt;/TITLE&gt;
    &lt;STYLE type="text/css"&gt;
      TABLE  { background: #ff0; border: solid black;
               empty-cells: hide }
      TR.top { background: red }
      TD     { border: solid black }
    &lt;/STYLE&gt;
  &lt;/HEAD&gt;
  &lt;BODY&gt;
    &lt;TABLE&gt;
      &lt;TR CLASS="top"&gt;
        &lt;TD&gt; 1
        &lt;TD rowspan="2"&gt; 2
        &lt;TD&gt; 3
        &lt;TD&gt; 4
      &lt;TR&gt;
        &lt;TD&gt; 5
        &lt;TD&gt;
    &lt;/TABLE&gt;
  &lt;/BODY&gt;
&lt;/HTML&gt;
</pre>

<p>might be formatted as follows:

<div class="figure">
  <p><img src="images/tbl-empty.png" alt="Table with three empty cells
  in bottom row">

  <p class="caption">Table with empty cells in the bottom row.
</div>
</div>

<p>Note that if the table has 'border-collapse: separate', the
background of the area given by the <span
class="propinst-border-spacing">'border-spacing'</span> property is
always the background of the table element. See <a
href="#separated-borders">the separated borders model</a>.

<h3><a name="width-layout">Table width algorithms:</a>
the <span class="propinst-table-layout">'table-layout'</span>
property</h3>

<p>CSS does not define an "optimal" layout for tables since, in many
cases, what is optimal is a matter of taste. CSS does define
constraints that user agents must respect when laying out a table.
User agents may use any algorithm they wish to do so, and are free to
prefer rendering speed over precision, except when the "fixed layout
algorithm" is selected.

<p>Note that this section overrides the rules that apply to
calculating widths as described in <a
href="visudet.html#Computing_widths_and_margins">section 10.3</a>. In
particular, if the margins of a table are set to '0' and the width to
'auto', the table will not automatically size to fill its containing
block. However, once the calculated value of 'width' for the table is
found (using the algorithms given below or, when appropriate, some
other UA dependent algorithm) then the other parts of section 10.3 do
apply. Therefore a table <em>can</em> be centered using left and right
'auto' margins, for instance.

<p>Future updates of CSS may introduce ways of making tables
automatically fit their containing blocks.


<!-- #include src=properties/table-layout.srb -->

<p>The <span class="propinst-table-layout">'table-layout'</span>
property controls the algorithm used to lay out the table cells, rows,
and columns. Values have the following meaning:

<dl>
  <dt><strong>fixed</strong> <dd>Use the fixed table layout algorithm

  <dt><strong>auto</strong> <dd>Use any automatic table la
1716
yout
  algorithm
</dl>

<p>The two algorithms are described below.

<h4><a name="fixed-table-layout">Fixed table layout</a></h4>

<p>With this (fast) algorithm, the horizontal layout of the table does
not depend on the contents of the cells; it only depends on the
table's width, the width of the columns, and borders or cell spacing.

<p>The table's width may be specified explicitly with the <span
class="propinst-width">'width'</span> property. A value of 'auto' (for
both 'display: table' and 'display: inline-table') means use the <a
href="#auto-table-layout">automatic table layout</a> algorithm.
However, if the table is a block-level table ('display: table') in
normal flow, a UA may (but does not have to) use the algorithm of <a
href="visudet.html#blockwidth">10.3.3</a> to compute a width and apply
fixed table layout even if the specified width is 'auto'.

<div class="example">
<p>If a UA supports fixed table layout when 'width' is 'auto', the
following will create a table that is 4em narrower than its containing
block:

<pre>
table { table-layout: fixed;
        margin-left: 2em;
        margin-right: 2em }
</pre>
</div>

<p>In the fixed table layout algorithm, the width of each column is
determined as follows:

<ol>
  <li>A column element with a value other than 'auto' for the <span
  class="propinst-width">'width'</span> property sets the width for
  that column.

  <li>Otherwise, a cell in the first row with a value other than
  'auto' for the <span class="propinst-width">'width'</span> property
  determines the width for that column. If the cell spans more than
  one column, the width is divided over the columns.

  <li>Any remaining columns equally divide the remaining horizontal
  table space (minus borders or cell spacing).
</ol>

<p>The width of the table is then the greater of the value of the
<span class="propinst-width">'width'</span> property for the table
element and the sum of the column widths (plus cell spacing or
borders). If the table is wider than the columns, the extra space
should be distributed over the columns.

<p>If a subsequent row has more columns than the greater of the number
determined by the table-column elements and the number determined by
the first row, then
additional columns may not be rendered. CSS&nbsp;2.1 does not define
the width of the columns and the table if they <em>are</em> rendered.
When using 'table-layout:
fixed', authors should not omit columns from the first row.

<p>In this manner, the user agent can begin to lay out the table once
the entire first row has been received. Cells in subsequent rows do
not affect column widths. Any cell that has content that overflows
uses the <span class="propinst-overflow">'overflow'</span> property to
determine whether to clip the overflow content.

<h4><a name="auto-table-layout">Automatic table layout</a></h4>

<p>In this algorithm (which generally requires no more than two
passes), the table's width is given by the width of its columns (and
intervening <a href="#borders">borders</a>). This algorithm reflects
the behavior of several popular HTML user agents at the writing of
this specification. UAs are not required to implement this algorithm
to determine the table layout in the case that <span
class="propinst-table-layout">'table-layout'</span> is 'auto'; they
can use any other algorithm even if it results in different behavior.

<p>Input to the automatic table layout must only include the width of
the containing block and the content of, and any CSS properties set
on, the table and any of its descendants.

<div class=note>
<p><em><strong>Note.</strong> This may be defined in more detail in
CSS3.</em>
</div>

<p><em>The remainder of this section is non-normative.</em>

<p>This algorithm may be inefficient since it requires the user agent
to have access to all the content in the table before determining the
final layout and may demand more than one pass.

<p>Column widths are determined as follows:

<ol>
  <li><p>Calculate the minimum content width (MCW) of each cell: the
  formatted content may span any number of lines but may not overflow
  the cell box. If the specified <span
  class="propinst-width">'width'</span> (W) of the cell is greater
  than MCW, W is the minimum cell width. A value of 'auto' means that
  MCW is the minimum cell width.

  <p>Also, calculate the "maximum" cell width of each cell: formatting
  the content without breaking lines other than where explicit line
  breaks occur.

  <li><p>For each column, determine a maximum and minimum column width
  from the cells that span only that column. The minimum is that
  required by the cell with the largest minimum cell width (or the
  column <span class="propinst-width">'width'</span>, whichever is
  larger). The maximum is that required by the cell with the largest
  maximum cell width (or the column <span
  class="propinst-width">'width'</span>, whichever is larger).

  <li><p>For each cell that spans more than one column, increase the
  minimum widths of the columns it spans so that together, they are at
  least as wide as the cell. Do the same for the maximum widths. If
  possible, widen all spanned columns by approximately the same
  amount.

  <li><p>For each column group element with a 'width' other than
  'auto', increase the minimum widths of the columns it spans, so that
  together they are at least as wide as the column group's 'width'.

</ol>

<p>This gives a maximum and minimum width for each column.

<p>The caption width minimum (CAPMIN) is determined by calculating for
each caption the minimum caption outer width as the MCW of a
hypothetical table cell that contains the caption formatted as
"display: block". The greatest of the minimum caption outer widths is
CAPMIN.

<p>Column and caption
widths influence the final table width as follows:

<ol>
  <li>If the 'table' or 'inline-table' element's <span
  class="propinst-width">'width'</span> property has a computed value
  (W) other than 'auto', the used width is
  the greater of W, CAPMIN, and the minimum width required by all the
  columns plus cell spacing or borders (MIN). If the used width is
  greater than MIN, the
  extra width should be distributed over the columns.

  <li>If the 'table' or 'inline-table' element has 'width: auto',
  the used width is the greater of the table's containing block width,
  CAPMIN, and MIN. However, if either CAPMIN or the maximum width
  required by the columns plus cell spacing or borders (MAX) is less
  than that of the containing block, use max(MAX, CAPMIN).
</ol>

<p>A percentage value for a column width is relative to the table
width. If the table has 'width: auto', a percentage represents a
constraint on the column's width, which a UA should try to satisfy.
(Obviously, this is not always possible: if the column's width is
'110%', the constraint cannot be satisfied.)

<div class="note">
<p><em><strong>Note.</strong> In this algorithm, rows (and row
groups) and columns (and column groups) both constrain and are
constrained by the dimensions of the cells they contain. Setting the
width of a column may indirectly influence the height of a row, and
vice versa.</em>
</div>

<h3><a name="height-layout">Table height algorithms</a></h3>

<p>The height of a table is given by the <span
class="propinst-height">'height'</span> property for the 'table' or
'inline-table' element. A value of 'auto' means that the height is the
sum of the row heights plus any cell spacing or borders. Any other
value is treated as a minimum height. CSS 2.1 does not define how
extra space is distributed when the 'height' property causes the table
to be taller than it otherwise would be.

<p class=note><em><strong>Note.</strong> Future
updates of CSS may specify this further.</em>

<p>The height of a 'table-row' element's box is calculated once the
user agent has all the cells in the row available: it is the maximum
of the row's computed <span class="propinst-height">'height'</span>,
the computed <span class="propinst-height">'height'</span> of each
cell in the row,
and the minimum height (MIN) required by the cells. A <span
class="propinst-height">'height'</span> value of 'auto' for a
'table-row' means the row height used for layout is MIN. MIN depends
on cell box heights and cell box alignment (much like the calculation
of a <a href="visudet.html#line-height">line box</a> height).