Refinement of CSS2 Table Captions

Proposal by Bernd Mielke and fantasai
Writeup by fantasai
Sanity checking by Chris Karnaze

Bernd Mielke has recently implemented support for CSS2 side-positioned captions in Mozilla, extending the work Chris Karnaze has done for top and bottom captions. In doing so, he has discovered some deficiencies in the spec's definition of caption layout. Most of these are simply the result of having very vaguely defined model. However, Bernd noticed some significant problems with placing the caption box alongside the table box, and so he decided to implement a slightly different model in which the caption box is placed within the table's margin. This document explains Mozilla's current table caption model and specifies an improved CSS table caption model we hope will be incorporated into a future revision of CSS.

Inside vs. Alongside the Table Margin

Problems with the CSS2 Model

Section 17.4 of CSS2 specifies that a side-positioned caption is placed alongside the table proper, thus: In a table with a left-positioned caption, the caption is placed between the table and the left containing block edge. The caption is separated from the container edge and table's margin box by its margins. The table is likewise separated from the caption's margin box and the opposite container edge by its margins.

There are, however, problems with the CSS2 model:

The table cannot be centered.

Suppose we try specifying auto margins on the table and caption:

If the auto margins are calculated for both the caption and the table before moving the caption to the side of the table, the box on the starting side will be centered and the other will be hanging outside the content area by its auto margin.

If the margins are calculated after side positioning, horizontal margins will equalize to take up the remaining space, leaving the table and caption separated from each other by a wide auto margin.

It may be possible to center the table and its caption as one unit if the joining margins are lengths and the outer ones were auto. However, what this really does in CSS2 is not clear. Also, it wouldn't degrade nicely in UAs without caption-side support: the table and the caption would be aligned to opposite sides.

Auto width is undefined

and discouraged. This means that caption widths must be explicitly specified, which does not allow for very fluid layouts.

Caption Position Influences Table's Centering

Moving the caption from one side to the other will cause the table to shift, and adding a caption moves a centered table off-center. As Bernd says,

I would like to keep the table centered on the containing block and let the caption, which is only a small description, not influence the position.

Mozilla's Caption Model

In Mozilla's caption model, the table caption is placed within the table's margin, thus: The caption box is placed in the space between the table's left margin edge and table's left border edge.

This makes centering the table easy: just set both table margins and the outer caption margin to auto. Caption auto width can be defined by using the margin as a constraint, and the table remains centered with respect ot the block no matter how much the caption moves around.

It is not possible to center the table and its caption together as a unit in this model. However, since its also not possible in the CSS2 model to center the table itself when it has a side-positioned caption, they are equal in this respect. Thus, the other advantages tip the balance in favor of this model, and we both feel that having the caption not influence table centering is more aesthetically pleasing anyway.

Proposed Calculations of Side-Positioned Caption Dimensions

Since Mozilla aims to implement the CSS2 specification as accurately as possible, its actual caption implementation is not as described here. Ignoring bugs in the implementation, however, it behaves pretty much as specified except vertical-align, if it's not set to middle or bottom, is always treated as top.

The caption's box properties are calculated according to the principle that the caption's dimensions must completely fill the table's side margin, where the table's side margin is defined as the box formed by the table's top and bottom border edges and its margin and border edge on the side to which the caption box has been assigned.

Horizontal Dimensions

Percentage widths and horizontal margins are calculated as for top- and bottom-positioned captions. auto widths and horizontal margins are calculated as if the caption were a regular non-replaced block whose containing block was the table's side margin. However, an auto-width caption must always be large enough to hold its contents. The minimum caption width is computed the same way as MCW for table cells. (See CSS2 Section 17.5.2)

If the table's margin is not wide enough to hold the caption, it expands.

Vertical Dimensions

Heights are calculated similarly to widths:

offset + 'margin-top' + 'border-top-width' + 'padding-top' + 'height' + 'padding-bottom' + 'border-bottom-width' + 'margin-bottom' >= height of table's border box
offset = vertical distance from table's top border edge to caption's top margin edge, due to vertical-align (down is positive)
  • Vertical percentages are calculated with respect to the table's border box height.
  • If both margins are auto, they equalize.
  • If either margin is auto and the height is auto, the height is the intrinsic height and the auto margin(s) calculate from the above restraints.
  • If both margins are given and vertical-align is not effective (see section on vertical-align), an auto height calculates to the greater of:
    • the height computed by making the above inequality an equation and solving for height
    • the intrinsic height
  • If the caption's dimensions are overconstrained, the bottom margin is treated as auto. Note that because the constraint is an inequality, this only happens when the expression's value is less than the table's border-box height.

Vertical Alignment

The effects of vertical-align values are as follows:

Same as 0%
Same as 50%
Same as 100%
Aligns the point x% of the way down the border box of the caption with the point x% down the border box of the table
Vertically offsets the top border edge of the caption box <length> down from the top border edge of the table

Setting the vertical-align property to any of these values causes auto height to always use the instrinsic height value.

All other values have no effect on caption position or size. Offset due to vertical-align is zero and height is calculated as specified for when vertical-align is not effective.

Capabilities of This Model

So what kinds of cool stuff can we do with this expanded caption model? Take a look:

Basic Centered Table with Caption

Caption in margin of centered table, 0.5em below the table's top border edge and 0.25em away from its left border edge. The distance from the caption to the containing block's left content edge and the table's bottom border edge is automatically determined. The caption fits inside the margin, and the table's still centered.

Why is This a Robust Model?

p {
	margin: 0;
	text-indent: 2em;
table {
	margin: 0.7em auto;
caption {
	caption-side: left;
	margin: 0.3em 0.2em;
	verical-align: -3em;

Here's something that can't be done gracefully with CSS2's model. The caption is positioned so that it begins 3em above the table. It's spaced from the end of the preceding paragraph (which doesn't have any margins) by its 0.3em top margin.

In CSS2, a -3em margin would offset the caption correctly, but it would also place the caption 2.3em on top of the preceding paragraph. Of course, one could compensate by adding 3em to the top table margin:

table { margin: 3.7em auto 0.7em; }

But then, what happens if there is no caption? The table would be spaced an unwanted 3em from the end of the paragraph.

The model described above, however, suffers no such consequence. The table's margin is still only 0.7em.

You might notice, too, that in this example the table with the caption has shifted slightly to the right of absolute center. This is because the long word 'Multiplication' has made caption's minimum width larger than the table's left margin. Instead of overwriting the first few columns, however, the caption has caused the table's margin to increase enough to accomodate its entire width, preserving the readability of the rendered table.

What Next?

Perhaps you've heard that CSS3 provides for vertical text...

The caption has two lines of text running vertically up the side of the table. The box is smaller than the table's border box height by the length of its top and bottom margins.

With a few small tweaks to recognize horizontal flow, this model can handle even extra-wordy vertical text captions without having a ridiculously long caption on small tables. And if you want long captions...

caption {
	margin: 1.5em .1em 1.5em auto;
	white-space: nowrap;
	vertical-align: middle;
A one line caption extends equally from the top and bottom of the table. It is separated from the blocks that precede and follow the table by its 1.5em margin.

What Can't Be Done With This?

Negative bottom table margins won't have an effect even with short captions because the auto margin stretches to the border edge, not the margin edge. This can probably be resolved by adding another calculation rule or two that accounts for the difference.


should preferably take place on the www-style mailing list. (We're both subscribed.) You can also contact us directly, via email.