CSS Repeated Headers and Footers

1. Introduction

A useful feature of the header and footer of [HTML] table has traditionally not fully been explain by CSS: when the table is fragmented across several pages or columns, the header and footer is repeated on each fragment.

[CSS2] and later [CSS-TABLES-3] have given some explanation about how this works, but do so by linking this behavior to the display type.

This specification instead explains it with a dedicated repeat-on-break property, and defines it in greater detail. It’s initial auto value triggers the legacy behavior of repeating the table header and footer, and setting it explicitly enables authors to get this effect on other elements, or to turn it off on table headers and footers where this is not desired.

Note: Fragmentation related behaviors, including repetition of table headers when fragmenting, have historically been better supported by print-oriented User Agents than by deskop or mobile browsers, as they attach greater importance to pagination. However, such features are by no means intended to be exclusive to print-oriented UAs, and support in browsers in encouraged.

1.1. Motivating scenarios

In no particular order, here are a few examples of situations where this property can be useful:

• On a table with multiple headers or footers, to select which one gets repeated.

• To turn off repetition for some tables when the effect is not desired.

• To repeat the caption of a figure when the figure is fragmented. Note: This would become even more useful if combined with a fragment specific selector to insert “(continued)” or some similar phrasing after the repeated caption.

• It is occasionally useful to style a table using some other display type, such as those defined in [CSS-FLEXBOX-1] or [CSS-GRID-1]. This property makes it possible to do so while keeping the ability to repeat relevant parts of the table when fragmenting.

• When pseudo elements like ::before and ::after are used for decorative purposes, it can be desirable to repeat them in case of fragmentation.

2. Module Interactions

• The following statements in Section 17.2 of [CSS2]:

  • 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'.

  • 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'.

• CSS Table 3 § 6.2 Repeating headers across pages

Note: This specification is not intended to contradict the behavior described in [CSS-TABLES-3], only to generalize it. Leaving the repeat-on-break property at its initial value is expected to produce the same behavior as the one described in CSS Table 3 § 6.2 Repeating headers across pages. If it does not this should be considered an error in this document. If you notice any such problem, please report it.

3. Repeating elements: the repeat-on-break property

This property enables authors to designate one child of an element as the repeatable header and one as the repeatable footer of that element. If this element is fragmented, they will be repeated at the beginning and end of each fragment. Beforehand, the children of that parent are reordered to make the repeatable header and repeatable footer first and last.

Values have the following meanings:

auto

The auto value computes to:

• header when the computed value of the display property is is table-header-group

• footer when the computed value of the display property is table-footer-group

• none otherwise

none

The element follows normal fragmentation rules, as defined in [CSS-BREAK-3]

header

The first child (in document order) of an element to have a computed value of header becomes the repeatable header of that element. header on subsequent siblings has no effect.

footer

The first child (in document order) of an element to have a computed value of footer becomes the repeatable footer of that element. footer on subsequent siblings has no effect.

An alternative approach would be to have the property apply to the parent rather than on the header and footer directly, and turn its first / last childern into a header / footer. The syntax would the become: auto | none | header || footer. This would simplify how this works by getting rid of reordering, and by reducing the amount of tree traversal needed to make this work. However, something else would then need to explain how the first table-header-group and table-footer-group get reordered, since they do have this behavior and it is currently underspecified. We would also need to define the interaction with the order property on flex items and grid items: presumably, just like with tables, we’d have to repeat the first/last child after reordering, which negates some of the tree traversal simplifications. Also, we would have to deal with situation where the first/last child of an elements are not Block-level elements, table-row-grouping elements, flex items, or grid items. Should we still reorder in that case, or should this make the property have no effect?

Add examples

3.1. Reordering

For the purpose of layout, if an element has a repeatable header child, that child is treated as if it was the first child of the element, and if it has a repeatable footer child, that child is treated as if it was the last child of the element. This also affects the painting order defined in CSS Flexbox 1 § 4.3 Flex Item Z-Ordering for flex items, in CSS Grid Layout 1 § 6.5 Z-axis Ordering: the z-index property for grid items, and in Appendix E of CSS2 for other elements.

For flex items and grid items, the effect is identical to that of the order property; repeatable headers behave is if they had the smallest order of all their siblings, repeatable footers as if they had the largest one.

This reordering does not affect ordering in non-visual media (such as speech), nor does it affect the default traversal order of sequential navigation modes (such as cycling through links, see e.g. tabindex [HTML5]).

As with reordering using the order property, authors must only use header (resp. footer) on elements that are not the first (resp. last) child when the visual order needs to be out-of-sync with the speech and navigation order; otherwise the underlying document source should be reordered instead. See CSS Flexbox 1 § 5.4.1 Reordering and Accessibility.

3.2. Repetition

If an element with a repeatable header is fragmented, the UA should repeat the repeatable header at the beginning of each fragment.

If an element with a repeatable footer is fragmented, the UA should repeat the repeatable footer at the end of each fragment, pushing content the next fragmentainer in the fragmentation context as necessary to make room for the repeatable footer.

Should this also apply to wrapped rows of a flex-wrap: wrap element in addition to fragmentation?

To account for the various rules and properties creating or suppressing break opportunities, to account for the prioritization of different classes of break-points, to avoid overflow or excessive fragmentation, or to strike an appropriate balance between performance and quality of layout, the UA may skip either or both of the repeatable header or the repeatable footer in some fragmentainers.

The exact algorithm to decide in with case to repeat or skip either or both of the repeatable header or the repeatable footer is up to the UA. However, the UA must guarantee progress through the content while ensuring that none of the content (including the repeatable header and footer) gets dropped. For that purpose, the algorithm must at least fulfil the following constraints:

• If repeatable header or a repeatable footer is too large to fit in its fragmentainer and if it is not being skipped, whether it overflows or is fragmented is determined by the usual rules of fragmentation.

• The UA must include the repeatable header at least once, at the beginning of the first fragment of it parent. If this first instance of the repeatable header is itself fragmented, the UA must not include any further content (including the repeatable footer until all the fragments of the repeatable header have been placed.

• The UA must include repeatable footer at least once, at the end of the last fragment of its parent.

• Other than when placing the first repeatable header and the last repeatable footer, if a fragmentainer is too small to fit any content other than the repeatable header and repeatable footer, then the UA must skip either or both of them to make room for the content.

In addition, in order to guarantee backwards compatibility with the behavior of tables in desktop browsers:

If

• the fragmentainer is a page, and

• the computed value of the display property on the repeatable header (resp. repeatable footer) is display: table-header-group (resp. display: table-footer-group), and

• the computed value of the break-inside property on the repeatable header (resp. repeatable footer) is break-inside: avoid, and

• the logical height of the repeatable header (resp. repeatable footer) when laid out in that fragmentainer would be equal to or smaller than 25% of the logical height of the page area.

then

the repeatable header (resp. repeatable footer) must not be skipped.

A UA that would only include the repeatable header and repeatable footer at the beginning, the end, and the positions required for compability with the behavior of tables in desktop browsers and skip them everywhere else would not directly violate the above constraints. Such an implementation would not however be useful, as it would bring no new capability to authors other than reordering, which is merely a side effect, not the main point of this feature. Implementations which only support the repeat-on-break: none and repeat-on-break: auto values may limit themselves to this minimalist interpretation. However, implementations must not support the repeat-on-break: header and repeat-on-break: footer values without making the repeatable header and repeatable footer actually repeat with display types other than display: table-header-group and display: table-footer-group. While the flexibility given to implementors makes this difficult to assertain via formal tests, ignoring this requirement would make an implementation non-conforming.

Should we try to specify repeat/skip the algorithm instead of leaving it up to the UA? Should we leave it up to the UA but more constraints on it?

Apendix A. Security and Privacy Considerations

This appendix is non-normative.

There are no known security or privacy impacts of this feature.

The W3C TAG is developing a Self-Review Questionnaire: Security and Privacy for editors of specifications to informatively answer. As far as currently known, here are the answers to the Questions to Consider:

Does this specification deal with personally-identifiable information?

No

Does this specification deal with high-value data?

No.

Does this specification introduce new state for an origin that persists across browsing sessions?

No.

Does this specification expose any other data to an origin that it doesn’t currently have access to?

No.

Does this specification enable new script execution/loading mechanisms?

No.

Does this specification allow an origin access to a user’s location?

No.

Does this specification allow an origin access to sensors on a user’s device?

No.

Does this specification allow an origin access to aspects of a user’s local computing environment?

No.

Does this specification allow an origin access to other devices?

No.

Does this specification allow an origin some measure of control over a user agent’s native UI?

No.

Does this specification expose temporary identifiers to the web?

No.

Does this specification distinguish between behavior in first-party and third-party contexts?

No.

How should this specification work in the context of a user agent’s "incognito" mode?

No difference in behavior is expected or needed.

Does this specification persist data to a user’s local device?

No.

Does this specification have a "Security Considerations" and "Privacy Considerations" section?

Yes, this is the role of this Appendix.

Does this specification allow downgrading default security characteristics?

No.