CSS Overflow Module Level 5

1. Introduction

This specification extends [CSS-OVERFLOW-4].

Scroll navigation controls

This section defines stylable scroll navigation controls with defined user interactions and accessible labels, and pseudo-classes which automatically construct them.

Redirection of Overflow

This section defines a highly experimental, exploratory new model for handling overflow by redirecting it into newly-generated fragmentation containers.

Note: At the time of writing, [CSS-OVERFLOW-4] is not completely finalized yet. To avoid accidental divergences and maintenance overhead, This specification is written as a delta specification over css-overflow Level 4. Once the level 4 specification is final, its content will be integrated into this specification, which will then replace it. Until then, this specification only contains additions and extensions to level 4.

2. Scroll navigation controls

2.1. Scroll markers

A scroll marker is any element or pseudo-element with a scroll target. An element or pseudo-element’s scroll target is the Element indicated by the scroll marker. Which elements are scroll markers, and what their scroll targets are, is host-language defined. The HTML <a> element and SVG <a> element are scroll markers, whose scroll target is the indicated part. While these navigational links can be created today, there is little feedback to the user regarding the current content being viewed, and the interaction model does not match the expectations of many modern accessible UI components.

This specification adds a mechanism for creating groups of scroll markers, and for automatically creating '::scroll-marker'' pseudo-elements. Within each group, the active marker reflects the current scroll position, and can be styled to give the user an indication of which section they are in.

Use cases include a table of contents with links to relevant contents, markers for scrolling carousel pages, and scrollable tab panels.

Add images representing these examples.

2.1.1. Scroll marker grouping

An element with a focusgroup attribute defines a scroll marker group container having a scroll marker group containing all of the scroll marker elements for which this is the nearest ancestor scroll marker group container.

The grouping of markers for scroll progress tracking should be separated from opting into focusgroup focus behavior.

A ::scroll-marker-group pseudo-element is the scroll marker group container for its contained ::scroll-marker pseudo-elements, which form a scroll marker group together.

2.1.2. The scroll-marker-group property

The scroll-marker-group property specifies whether the scroll container should have a '::scroll-marker-group' pseudo-element created, and its position relative to the scroll container.

none

The scroll container does not create a '::scroll-marker-group' pseudo-element.

before

The scroll container generates a ::scroll-marker-group pseudo-element whose box is an immediate preceding sibling to its originating element.

after

The scroll container generates a ::scroll-marker-group pseudo-element whose box is an immediate following sibling to its originating element.

2.1.3. The ::scroll-marker-group pseudo-element

The ::scroll-marker-group fully stylable pseudo-element is generated by a scroll container element having a computed scroll-marker-group property that is not none, adjacent to the scroll container.

The following additions are recommended for the default UA stylesheet to ensure that the generation of scroll marker pseudo-elements does not invalidate the layout of the site:

/* The generation of ::scroll-marker pseudo-elements shouldn’t
 * invalidate layout outside of this pseudo-element. */
::scroll-marker-group { contain: size !important; }

The scroll-marker-group implicitly behaves as a single focusable component, establishing a focusgroup.

2.1.4. The ::scroll-marker pseudo-element

Similar to ::before and ::after, all elements can have a ::scroll-marker pseudo-element, which is collected into the ::scroll-marker-group of the nearest scroll container ancestor, and scrolls to the element when activated.

When the computed content value of a ::scroll-marker pseudo-element is not none and its nearest ancestor scroll container scroll container has a computed scroll-marker-group property that is not none, the pseudo-element generates a box attached as a child of the ::scroll-marker-group pseudo-element’s generated box on its nearest ancestor scroll container. These boxes are added in the tree order of their originating element.

These pseudo-elements have an indicated scroll target of their originating element. They behave as an element with a tabindex of -1, making them focusable within their '::scroll-marker-group' either by arrow key navigation within the group, or via the tab key when currently active or when no other ::scroll-marker is active and this is the first marker in the group, ensuring the group has a guaranteed tab stop.

2.1.5. Selecting The Active Scroll Marker: the :target-current pseudo-class

Exactly one scroll marker within each scroll marker group is determined to be active at a time. Such "active" scroll markers match the :target-current pseudo-class.

a:target-current {
  font-weight: bold;
}

A scrolling operation might animate towards a particular position (e.g. scrollbar arrow clicks, arrow key presses, "behavior: smooth" programmatic scrolls) or might directly track a user’s input (e.g. touch scrolling, scrollbar dragging). In either case, the user agent chooses an 'eventual scroll position' to which the scroller will reach. This ensures that the relevant marker is activated immediately.

This 'eventual scroll position' is used to determine the active marker within each scroll marker group. Since markers themselves may represent just the start of the content (e.g. headers), we consider the active marker to be the first one which we are at or beyond the scroll position of.

2.1.6. Activation behavior

2.1.7. Focus behavior

When a scroll marker control is activated, the next tabindex-ordered focus navigation will focus the scroll target if it is focusable, otherwise, it will find the next focusable element from this element as though it were focused.

2.2. Scroll Buttons

The ::scroll-button( <scroll-button-direction> ) pseudo-elements are generated on scroll containers when their computed content value is not none. They generate boxes as if they were immediate children of their originating element, with content as specified by content. They exist after their originating element’s ::scroll-marker-group pseudo-element (when used with scroll-marker-group: before) and before its ::before pseudo-element, if those exist.

Four distinct ::scroll-button() pseudo-elements can exist on a scroll container, each associated with a logical direction, based on their originating element’s writing mode: in order, block-start, inline-start, block-end, and inline-end. The ::scroll-button() pseudo-elements are both focusable and activatable by default, with their activation behavior being to scroll their originating element by one "page" in their associated direction, similar to pressing PgUp/PgDn keys. (Usually, this will be about 85% of the scrollport size.) Like those keys, this scroll has an intended direction and end position.

[CSSOM-VIEW-1] will grow a "scroll by pages" algorithm, at which point this can reference that. See the resolution on issue #10914.

Is this the best order for the buttons? This does match the usual ordering of logical directions in CSS, but similar buttons created manually are usually either ordered with verticals and horizontals each grouped together (aka block-start/block-end then inline-start/inline-end) or the verticals "around" the horizontals (aka block-start/inline-start/inline-end/block-end).

The four ::scroll-button() pseudo-elements are individually selected by the selector’s argument. The possible <scroll-button-direction> values are:

up

down

left

right

Selects the ''::scroll-button()' corresponding to the given physical direction.

block-start

block-end

inline-start

inline-end

Selects the indicated ::scroll-button() pseudo-element.

prev

Selects either the block-start or inline-start ::scroll-button(), whichever’s axis has more "scrollable pages" in the originating element: the originating element’s scrollable overflow height divided by its scrollport height, or the same but for widths.

If both dimensions are equally sized, selects the block-start ::scroll-button().

For example, say the originating element was 800px wide and 500px tall, while its scrollable overflow area was 1200px wide and 1000px tall. The horizontal scrolling thus represents 1.5 "pages" (1200/800), while the vertical scrolling represents 2 "pages" (1000/500), so (assuming the element is in English) the ::scroll-button(prev) selector would select the block-start button.

next

Identical to prev, except it selects the block-end or inline-end ::scroll-button() instead.

Do we want to add some multi-button keywords to make it easier to style several buttons the same way? In particular, all is probably useful, but maybe also horizontal/vertical/block/inline.

The ::scroll-button()s are fully stylable pseudo-elements: there is no restriction on what properties apply to them.

The UA stylesheet needs to specify that ::scroll-button()s are styled identically to the button element.

2.3. Focus Navigation Order

The above features generate several focusable pseudo-elements. While these pseudo-elements have a defined position in the element tree, this isn’t an optimal position for focus navigation (aka "tab order") for these controls.

Instead, focus navigation between a scroll container and the various pseudo-elements defined in this section goes in the following order:

1. The ::scroll-marker-group pseudo-elements of the scroll container, if it is set to scroll-marker-group: before.

   Note: The individual ::scroll-marker pseudo-elements generated by the scroll containers descendants are reparented underneath this ::scroll-marker-group, and navigated together as a "focus group".

2. The ::scroll-button() pseudo-elements, in the order they’re defined as existing in.

3. The scroll container itself, and its contents, in the normal focus order they would be in.

4. The ::scroll-marker-group pseudo-elements of the scroll container, if it is set to scroll-marker-group: after.

Appendix A: Redirection of Overflow

This section is highly experimental. It documents current attempts at extending the capabilities of the continue property to solve additional use cases. However, it does not currently have consensus. It is presented here to encourage discussion, but non-experimental implementation is not recommended.

In CSS Level 1 [CSS1], placing more content than would fit inside an element with a specified size was generally an authoring error. Doing so caused the content to extend outside the bounds of the element, which would likely cause that content to overlap with other elements.

CSS Level 2 [CSS2] introduced the overflow property, which allows authors to have overflow be handled by scrolling, which means it is no longer an authoring error. It also allows authors to specify that overflow is handled by clipping, which makes sense when the author’s intent is that the content not be shown. This was further refined in the CSS Overflow Module Level 3 [CSS-OVERFLOW-3].

However, scrolling is not the only way to present large amounts of content, and may even not be the optimal way. After all, the codex replaced the scroll as the common format for large written works because of its advantages.

This specification introduces a mechanism for Web pages to specify that an element of a page should handle overflow through pagination rather than through scrolling.

This specification also extends the concept of overflow in another direction. Instead of requiring that authors specify a single area into which the content of an element must flow, this specification allows authors to specify multiple fragments, each with their own dimensions and styles, so that the content of the element can flow from one to the next, using as many as needed to place the content without overflowing.

In both of these cases, implementations must break the content in the block-progression dimension. Implementations must do this is described in the CSS Fragmentation Module [CSS-BREAK-3].

Channeling Overflow: the continue property

The continue property gives authors the ability to request that content that does not fit inside an element be fragmented (in the sense of [CSS-BREAK-3]), and provides alternatives for where the remaining content should continue.

Notably, this property explains traditional pagination, and extends it further.

The naming of this property and its values is preliminary. This was initially proposed as "fragmentation: auto | none | break | clone | page" in https://lists.w3.org/Archives/Public/www-style/2015Jan/0357.html, and there is not yet wide agreement as to which naming is better.

This property is meant to generalize and replace region-fragment. Once it is sufficiently stable in this specification, region-fragment should be removed from the regions specification in favor of this.

Note: continue: fragments replaces "overflow:fragments" from earlier versions of this specification, while continue: paginate replaces "overflow: paged-x | paged-y | paged-x-controls | paged-y-controls"

auto

auto may only occur as a computed value if the element is a CSS Region other than the last one in a region chain. Content that doesn’t fit is pushed to the next region of the chain.

In all other cases, auto computes to one of the other values.

this is different from the definition in CSS Overflow 4 § 5.3 Fragmentation of Overflow: the continue property, where the specified value is the computed value. Which is model better?

overflow

Content that doesn’t fit overflows, according to the overflow property

paginate

Content that doesn’t fit paginates. This creates a paginated view inside the element similar to the way that 'overflow: scroll' creates a scrollable view.

See paginated overflow

Note: Print is effectively "continue: paginate" on the root.

fragments

content that doesn’t fit causes the element to copy itself and continue laying out.

See fragment overflow.

The computed value of the continue for a given element or pseudo element is determined as follow:

1. On elements or pseudo elements with layout containment (see [CSS-CONTAIN-1]), if the specified value is auto or fragments then the computed value is overflow.
2. Otherwise, if the specified value is auto
   1. On a CSS Region other than the last one in a region chain, the computed value is auto
   2. On a page the computed value is paginate
   3. On a fragment box the computed value is fragments
   4. Otherwise, the computed value is overflow
3. Otherwise, if the specified value is fragments
   1. On a page the computed value is paginate
   2. Otherwise, the computed value is the specified value
4. In all other cases, the computed value is the specified value

If we introduce a pseudo element that can select columns in a multicol, we would need to specify that auto computes to auto on it, or introduce a new value and have auto compute to that (but what would that value compute to on things that aren’t columns?).

Note: For background discussions leading to this property, see these threads: discussion of overflow, overflow-x, overflow-y and overflow-style and proposal for a fragmentation property

Paginated overflow

This section introduces and defines the meaning of the paginate value of the continue property.

Write this section

Pages should be possible to style with @page rules. How does that work for nested pages?

@media (overflow-block: paged), (overflow-block: optional-paged) {
  :root {
    continue: paginate;
  }
}

Traditional pagination (e.g. when printing) assumes that :root is contained in the page box, rather than having the page box be a pseudo element child of :root. Can we work around that using something similar to fragment boxes? Or maybe by having a fragment box (reproducing :root) inside a page box inside :root?

How does the page box model work when it is a child of a regular css box?

The initial proposal in [CSS3GCPM] and implementation from Opera used 4 values instead of paginate: "paged-x | paged-y | paged-x-controls | paged-y-controls". Should this property also include these values, or are they better handled as separate properties? (e.g.: "pagination-layout: auto | horizontal | vertical", "pagination-controls: auto | none")

Ability to display N pages at once rather than just one page at once? Could this be a value of "pagination-layout", such as: "pagination-layout: horizontal 2;"

Brad Kemper has proposed a model for combining pagination and fragment overflow, which also deals with displaying multiple pages. http://www.w3.org/mid/FF1704C5-D5C1-4D6F-A99D-0DD094036685@gmail.com

The current implementation of paginated overflow uses the overflow/overflow-x/overflow-y properties rather than the overflow-style property as proposed in the [CSS3GCPM] draft (which also matches the [CSS3-MARQUEE] proposal). or the continue property as described here.

Fragmented Overflow

This section introduces and defines the meaning of the fragments value of the continue property.

When the computed value of continue for an element is fragments, and implementations would otherwise have created a box for the element, then implementations must create a sequence of fragment boxes for that element. (It is possible for an element with continue: fragments to generate only one fragment box. However, if an element’s computed continue is not fragments, then its box is not a fragment box.) Every fragment box is a fragmentation container, and any overflow that would cause that fragmentation container to fragment causes another fragment box created as a next sibling of the previous one. Or is it as though it’s a next sibling of the element? Need to figure out exactly how this interacts with other box-level fixup. Additionally, if the fragment box is also a multi-column box (as defined in [css-multicol-1] though it defines multi-column container) any content that would lead to the creation of overflow columns [css-multicol-1] instead is flown into an additional fragment box. However, fragment boxes may themselves be broken (due to fragmentation in a fragmentation context outside of them, such as pages, columns, or other fragment boxes); such breaking leads to fragments of the same fragment box rather than multiple fragment boxes. (This matters because fragment boxes may be styled by their index; such breaking leads to multiple fragments of a fragment box with a single index. This design choice is so that breaking a fragment box across pages does not break the association of indices to particular pieces of content.) Should a forced break that breaks to an outer fragmentation context cause a new fragment of a single fragment box or a new fragment box? Should we find a term other than fragment box here to make this a little less confusing?

What if we want to be able to style the pieces of an element split within another type of fragmentation context? These rules prevent ever using ::nth-fragment() for that, despite that the name seems the most logical name for such a feature.

<!DOCTYPE HTML><title>Breaking content into
  equal-sized cards</title>
<style>
  .in-cards {
    continue: fragments;

    width: 13em;
    height: 8em;

    padding: 4px;
    border: medium solid blue;
    margin: 6px;

    font: medium/1.3 Times New
      Roman, Times, serif;
  }
</style>
<div class="in-cards">
  In this example, the text in the div
  is broken into a series of cards.
  These cards all have the same style.
  The presence of enough content to
  overflow one of the cards causes
  another one to be created.  The second
  card is created just like it’s the
  next sibling of the first.
</div>

<!DOCTYPE HTML><style>
  .article {
    continue: fragments;
  }
  .article::first-letter {
    font-size: 2em;
    line-height: 0.9;
  }
  .article::nth-fragment(1) {
    font-size: 1.5em;
    max-lines: 3;
  }
  .article::nth-fragment(2) {
    column-count: 2;
  }
</style>
<div class="article">
  ...
</div>

We should specify that continue: fragments does not apply to at least some table parts, and perhaps other elements as well. We need to determine exactly which ones.

This specification needs to say which type of fragmentation context is created so that it’s clear which values of the break-* properties cause breaks within this context. We probably want break-*: region to apply.

This specification needs a processing model that will apply in cases where the layout containing the fragments has characteristics that use the intrinsic size of the fragments to change the amount of space available for them, such as [CSS3-GRID-LAYOUT]. There has already been some work on such a processing model in [CSS-REGIONS-1], and the work done on a model there, and the editors of that specification, should inform what happens in this specification.

Fragment styling

The ::nth-fragment() pseudo-element

The ::nth-fragment() pseudo-element is a pseudo-element that describes some of the fragment boxes generated by an element. The argument to the pseudo-element takes the same syntax as the argument to the :nth-child() pseudo-class defined in [SELECT], and has the same meaning except that the number is relative to fragment boxes generated by the element instead of siblings of the element.

Selectors that allow addressing fragments by counting from the end rather than the start are intentionally not provided. Such selectors would interfere with determining the number of fragments.

Depending on future discussions, this ::nth-fragment(an+b) syntax may be replaced with the new ::fragment:nth(an+b) syntax.

Styling of fragments

Should this apply to continue:fragments only, or also to continue:paginate? (If it applies, then stricter property restrictions would be needed for continue:paginate.)

In the absence of rules with ::nth-fragment() pseudo-elements, the computed style for each fragment box is the computed style for the element for which the fragment box was created. However, the style for a fragment box is also influenced by rules whose selector’s subject [SELECT] has an ::nth-fragment() pseudo-element, if the 1-based number of the fragment box matches that ::nth-fragment() pseudo-element and the selector (excluding the ::nth-fragment() pseudo-element) matches the element generating the fragments.

When determining the style of the fragment box, these rules that match the fragment pseudo-element cascade together with the rules that match the element, with the fragment pseudo-element adding the specificity of a pseudo-class to the specificity calculation. Does this need to be specified in the cascading module as well?

<!DOCTYPE HTML><style>
  .bouncy-columns {
    continue: fragments;
    width: 6em;
    height: 10em;
    float: left;
    margin: 1em;
    font: medium/1.25 Times New
      Roman, Times, serif;
  }
  .bouncy-columns::nth-fragment(1) {
    background: aqua; color: black;
    transform: rotate(-3deg);
  }
  .bouncy-columns::nth-fragment(2) {
    background: yellow; color: black;
    transform: rotate(3deg);
  }
</style>
<div class="bouncy-columns">
  ...
</div>

Styling an ::nth-fragment() pseudo-element with the continue property does take effect; if a fragment box has a computed value of continue other than fragments then that fragment box is the last fragment. However, overriding continue on the first fragment does not cause the fragment box not to exist; whether there are fragment boxes at all is determined by the computed value of overflow for the element.

Styling an ::nth-fragment() pseudo-element with the content property has no effect; the computed value of content for the fragment box remains the same as the computed value of content for the element.

Specifying display: none for a fragment box causes the fragment box with that index not to be generated. However, in terms of the indices used for matching ::nth-fragment() pseudo-elements of later fragment boxes, it still counts as though it was generated. However, since it is not generated, it does not contain any content.

Specifying other values of display, position, or float is permitted, but is not allowed to change the inner display type. (Since continue only applies to block containers, flex containers, and grid containers). Need to specify exactly how this works

To match the model for other pseudo-elements where the pseudo-elements live inside their corresponding element, declarations in ::nth-fragment() pseudo-elements override declarations in rules without the pseudo-element. The relative priority within such declarations is determined by normal cascading order (see [CSS2]).

Styles specified on ::nth-fragment() pseudo-elements do affect inheritance to content within the fragment box. In other words, the content within the fragment box must inherit from the fragment box’s style (i.e., the pseudo-element style) rather than directly from the element. This means that elements split between fragment boxes may have different styles for different parts of the element.

This inheritance rule allows specifying styles indirectly (by using explicit inherit or using default inheritance on properties that don’t apply to ::first-letter) that can’t be specified directly (based on the rules in the next section). This is a problem. The restrictions that apply to styling inside fragments should also apply to inheritance from fragments.

<!DOCTYPE HTML><style>
  .article {
    continue: fragments;
  }
  .article::nth-fragment(1) {
    font-size: 1.5em;
    margin-bottom: 1em;
    height: 4em;
  }
  .article::nth-fragment(2) {
    margin-left: 5em;
    margin-right: 2em;
  }
</style>
<div class="article">
  The <code>font-size</code> property...
</div>

Styling inside fragments

Should this apply to continue:fragments only, or also to continue:paginate?

The ::nth-fragment() pseudo-element can also be used to style content inside of a fragment box. Unlike the ::first-line and ::first-letter pseudo-elements, the ::nth-fragment() pseudo-element can be applied to parts of the selector other than the subject: in particular, it can match ancestors of the subject. However, the only CSS properties applied by rules with such selectors are those that apply to the ::first-letter pseudo-element.

To be more precise, when a rule’s selector has ::nth-fragment() pseudo-elements attached to parts of the selector other than the subject, the declarations in that rule apply to a fragment (or pseudo-element thereof) when:

1. the declarations are for properties that apply to the ::first-letter pseudo-element,
2. the declarations would apply to that fragment (or pseudo-element thereof) had those ::nth-fragment() pseudo-elements been removed, with a particular association between each sequence of simple selectors and the element it matched, and
3. for each removed ::nth-fragment() pseudo-element, the fragment lives within a fragment box of the element associated in that association with the selector that the pseudo-element was attached to, and whose index matches the pseudo-element.

<!DOCTYPE HTML><style>
  .dark-columns {
    continue: fragments;
    width: 6em;
    height: 10em;
    float: left;
    margin-right: 1em;
    font: medium/1.25 Times New
      Roman, Times, serif;
  }
  .dark-columns::nth-fragment(1) {
    background: aqua; color: black;
  }
  .dark-columns::nth-fragment(1) :link {
    color: blue;
  }
  .dark-columns::nth-fragment(1) :visited {
    color: purple;
  }
  .dark-columns::nth-fragment(2) {
    background: navy; color: white;
  }
  .dark-columns::nth-fragment(2) :link {
    color: aqua;
  }
  .dark-columns::nth-fragment(2) :visited {
    color: fuchsia;
  }
</style>
<div class="dark-columns">
  ...
</div>

Appendix C: Privacy Considerations

This specification introduces no new privacy considerations.

Appendix D: Security Considerations

This specification introduces no new security considerations.

Changes Since Level 4

TBD

Acknowledgments

Thanks especially to the feedback from Rossen Atanassov, Bert Bos, Tantek Çelik, John Daggett, fantasai, Daniel Glazman, Vincent Hardy, Håkon Wium Lie, Peter Linss, Robert O’Callahan, Florian Rivoal, Alan Stearns, Steve Zilles, and all the rest of the www-style community.