CSS Overflow Module Level 3

1. Introduction

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 specification introduces the long-standing de-facto overflow-x and overflow-y properties, adds a clip value, and defines overflow handling more fully.

[Something something max-lines.]

Note: This specification also reproduces the definition of the text-overflow property previously defined in [CSS-UI-3], with no addition or modification, in order to present text-overflow and block-ellipsis together.

1.1. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

1.2. Module Interactions

This module replaces (supersedes) and extends features defined in [CSS2] section 11.1 Overflow and clipping and [CSS-UI-3] section 5.2. Overflow Ellipsis: the text-overflow property.

2. Overflow Concepts and Terminology

CSS uses the term overflow to describe the contents of a box that extend outside one of that box’s edges (i.e., its content edge, padding edge, border edge, or margin edge). The term might be interpreted as elements or features that cause this overflow, the non-rectangular region occupied by these features, or, more commonly, as the minimal rectangle that bounds that region. A box’s overflow is computed based on the layout and styling of the box itself and of all descendants whose containing block chain includes the box.

In most cases, overflow can be computed for any box from the bounds and properties of that box itself, plus the overflow of each of its children. However, this is not always the case; for example, when transform-style: preserve-3d [CSS3-TRANSFORMS] is used on some of the children, any of their descendants with transform-style: preserve-3d must also be examined.

There are two different types of overflow, which are used for different purposes by the UA:

• ink overflow
• scrollable overflow

2.1. Ink Overflow

The ink overflow of a box is the part of that box and its contents that creates a visual effect outside of the box’s border box. Ink overflow is the overflow of painting effects defined to not affect layout or otherwise extend the scrollable overflow area, such as box shadows, border images, text decoration, overhanging glyphs (with negative side bearings, or with ascenders/descenders extending outside the em box), outlines, etc.

Since some effects in CSS (for example, the blurs in text-shadow [CSS-TEXT-3] and box-shadow [CSS-BACKGROUNDS-3], which are theoretically infinite) do not define what visual extent they cover, the extent of the ink overflow is undefined.

The ink overflow area is the non-rectangular area occupied by the ink overflow of a box and its contents, and the ink overflow rectangle is the minimal rectangle whose axes are aligned to the box’s axes and that contains the ink overflow area. Note that the ink overflow rectangle is a rectangle in the box’s coordinate system, but might be non-rectangular in other coordinate systems due to transforms. [CSS3-TRANSFORMS]

Any overflow of replaced content is always ink overflow (as opposed to scrollable overflow).

2.2. Scrollable Overflow

The scrollable overflow of a box is the set of things extending outside of that box’s padding edge for which a scrolling mechanism needs to be provided.

The scrollable overflow area is the non-rectangular region occupied by the scrollable overflow, and the scrollable overflow rectangle is the minimal rectangle whose axes are aligned to the box’s axes and that contains the scrollable overflow area.

The scrollable overflow area is the union of:

• The scroll container’s own padding box.
• All line boxes directly contained by the scroll container.
• The border boxes of all boxes for which it is the containing block and whose border boxes are positioned not wholly in the unreachable scrollable overflow region, accounting for transforms by projecting each box onto the plane of the element that establishes its 3D rendering context. [CSS3-TRANSFORMS]

  Is this description of handling transforms sufficiently accurate?

  Border boxes with zero area do not affect the scrollable overflow area.

• The margin areas of grid item and flex item boxes for which the box establishes a containing block.

  The UA may additionally include the margin areas of other boxes for which the box establishes a containing block; however, the conditions under which such margin areas are included is undefined in this level. This needs further testing and investigation; is therefore deferred in this draft.

• The scrollable overflow areas of all of the above boxes (including zero-area boxes and accounting for transforms as described above), provided they themselves have overflow: visible (i.e. do not themselves trap the overflow) and that scrollable overflow is not already clipped (e.g. by the clip property or the contain property).

  Note: The mask-* properties [CSS-MASKING-1] do not affect the scrollable overflow area.

  Need to evaluate what should/should not clip scrollable overflow. [Issue #8607]

• Additional padding added to the scrollable overflow rectangle as necessary to enable scroll positions that satisfy the requirements of both place-content: start and place-content: end alignment.

  Note: This padding represents, within the scrollable overflow rectangle, the box’s own padding so that when its content is scrolled to its end, there is padding between the edge of its in-flow (or floated) content and the border edge of the box. It typically ends up being exactly the same size as the box’s own padding, except in a few cases—​such as when an out-of-flow positioned element, or the visible overflow of a descendent, has already increased the size of the scrollable overflow rectangle outside the conceptual “content edge” of the scroll container’s content.

  

Additionally, due to Web-compatibility constraints (caused by authors exploiting legacy bugs to surreptitiously hide content from visual readers but not search engines and/or speech output), UAs must clip any content in the unreachable scrollable overflow region.

Note: The content-distribution properties can alter the unreachable scrollable overflow region to ensure that a scroll container’s alignment subject is reachable after alignment. [CSS-ALIGN-3]

Note: The scrollable overflow rectangle is always a rectangle in the box’s own coordinate system, but might be non-rectangular in other coordinate systems due to transforms [CSS3-TRANSFORMS]. This means scrollbars can sometimes appear when not actually necessary.

2.3. Scrolling Overflow

A box’s overflow can be visible or clipped. CSS also allows a box to be a scroll container that allows clipped parts of its scrollable overflow area to be scrolled into view. The visual “viewport” of a scroll container (through which the scrollable overflow area can be viewed) coincides with its padding box, and is called the scrollport. A box’s nearest scrollport is the scrollport of its nearest scroll container ancestor.

Scrolling operations can be initiated by the user (for example, by manipulating a scrollbar, swiping a touchscreen, or using keyboard controls) or by script (for example, by the scrollIntoView() or focus() APIs). The initial position of the scrollable overflow rectangle within the scrollport before any scrolling operations take effect is the initial scroll position. The initial scroll position is typically dependent on the scroll container’s writing mode, and, unless otherwise specified, coincides with its scroll origin position. For example, scroll-initial-target property can be used to change the initial scroll position. [CSS-SCROLL-SNAP-2]

A scroll position is a particular alignment of the scrollable overflow rectangle within its scrollport. It is associated with a scroll offset which is its distance from the scroll origin.

The scroll origin is the anchor coordinate of the scrollable overflow rectangle, from which the scrollable overflow rectangle expands. Unless otherwise specified, it is the block-start inline-start corner of the scrollable overflow rectangle. (For example, in a flex container it is the main-start cross-start corner.) Unless otherwise adjusted (e.g. by content alignment [css-align-3]), the area beyond the scroll origin in either axis is considered the unreachable scrollable overflow region: content rendered here is not accessible to the reader, see § 2.2 Scrollable Overflow. A scroll container is said to be scrolled to its scroll origin when its scroll origin coincides with the corresponding corner of its scrollport. This scroll position, the scroll origin position, usually, but not always, coincides with the initial scroll position.

Check whether things like baseline alignment depend on the initial scroll position or the scroll origin position.

This doesn’t define a coordinate system for scroll offsets. Whether they increase downward/rightward, block/inline-axis endward, or away from the scroll origin is not defined. Should each API define its coordinate model?

The root viewport, which scrolls the page canvas, uses the principal writing mode for determining its scroll origin and initial scroll position.

Note: In the case where a scroll container (or one of its ancestors) is the target of a graphical transform, the UA might need to take this transform into account when mapping user inputs to scrolling operations. For instance, on a touch screen where the user scrolls by directly dragging the content, the transform would be expected to be taken into account to match the direction of scrolling to the gesture. On the other hand, other user inputs (such as the Page Down key, or a 1D scroll wheel) might be more naturally interpreted ignoring the transform. Choosing the appropriate behavior for each scrolling mechanism is the responsibility of the UA.

3. Scrolling and Clipping Overflow

3.1. Managing Overflow: the overflow-x, overflow-y, and overflow properties

These properties specify whether a box’s overflow is clipped, and if so, whether it is a scroll container.

The overflow-x property specifies the handling of overflow in the horizontal axis (i.e., overflow from the left and right sides of the box), and the overflow-y property specifies the handling of overflow in the vertical axis (i.e., overflow from the top and bottom sides of the box).

The overflow-block and overflow-inline properties likewise specify the handling of overflow in the block and inline axis, respectively

These four properties form a logical property group together with the overflow shorthand, and interact as defined in CSS Logical Properties 1 § 4 Flow-Relative Box Model Properties.

The overflow property is a shorthand property that sets the specified values of overflow-x and overflow-y in that order. If the second value is omitted, it is copied from the first.

Values have the following meanings:

visible

There is no special handling of overflow, that is, the box’s content is rendered outside the box if positioned there. The box is not a scroll container.

hidden

This value indicates that the box’s content is clipped to its padding box and that the UA must not provide any scrolling user interface to view the content outside the clipping region, nor allow scrolling by direct intervention of the user, such as dragging on a touch screen or using the scrolling wheel on a mouse. However, the content must still be scrollable programmatically, for example using the mechanisms defined in [CSSOM-VIEW], and the box is therefore still a scroll container.

clip

This value indicates that the box’s content is clipped to its overflow clip edge and that no scrolling user interface should be provided by the UA to view the content outside the clipping region. In addition, unlike overflow: hidden which still allows programmatic scrolling, overflow: clip forbids scrolling entirely, through any mechanism, and therefore the box is not a scroll container.

Unlike hidden, this value does not cause the element to establish a new formatting context.

Note: Authors who also want the box to establish a formatting context may use display: flow-root together with overflow: clip.

scroll

This value indicates that the content is clipped to the padding box, but can be scrolled into view (and therefore the box is a scroll container). Furthermore, if the user agent uses a scrolling mechanism that is visible on the screen (such as a scroll bar or a panner), that mechanism should be displayed whether or not any of its content is clipped. This avoids any problem with scrollbars appearing and disappearing in a dynamic environment. When the target medium is print, overflowing content may be printed; it is not defined where it may be printed.

auto

Like scroll when the box has scrollable overflow; like hidden otherwise. Thus, if the user agent uses a scrolling mechanism that is visible on the screen (such as a scroll bar or a panner), that mechanism will only be displayed if there is overflow.

The scroll, auto, and hidden values are known as the scrollable values of overflow. The visible and clip values are known as the non-scrollable values.

The visible/clip values of overflow compute to auto/hidden (respectively) if one of overflow-x or overflow-y is neither visible nor clip. On replaced elements, a computed hidden value further resolves to a used value of clip.

If the computed value of overflow on a block box is neither visible nor clip nor a combination thereof, it establishes an independent formatting context for its contents.

User agents must also support the overlay keyword as a legacy value alias of auto.

3.1.1. Interaction of visibility and overflow

If the computed value of the visibility property is hidden (or collapse when it has the same effect as hidden), and overflow is either scroll or auto, then:

• The user agent must not make any scrolling mechanism visible. To the extent that the scrolling mechanism that would normally be visible in the absence of visibility: hidden affects layout, it continues to do so, but is not painted.

• As would be the case with overflow: hidden, scrolling directly triggered by user interactions is disabled, but programmatic scrolling continues to take effect.

• The lack of interactive direct scrolling is enforced even if the user interacts (e.g. with a mouse scrolling wheel) with a descendent of the visibility: hidden scroll container that is itself set to visibility: visible.

3.1.2. Interaction of border-radius and overflow

As mentioned in CSS Backgrounds 3 § 4.3 Corner Clipping, the clipping region established by overflow can be rounded:

• When overflow-x and overflow-y compute to hidden, scroll, or auto, the clipping region is rounded based on the border radius, adjusted to the padding edge, as described in CSS Backgrounds 3 § 4.2 Corner Shaping.

• When both overflow-x and overflow-y compute to clip, the clipping region is rounded as described in § 3.2 Expanding Clipping Bounds: the overflow-clip-margin property.

• However, when one of overflow-x or overflow-y computes to clip and the other computes to visible, the clipping region is not rounded.

3.1.3. Overflow in Print and Other Static Media

Since scrolling is not possible in static media (such as print) authors should be careful to make content accessible in such media, for example by using @media print, (update: none) { … } to adjust layout such that all relevant content is simultaneously visible.

On scroll containers in non-interactive media with an overflow value of auto or scroll (but not hidden) UAs may display an indication of any scrollable overflow, such as by displaying scrollbars or an ellipsis.

Note: Not all paged media is non-interactive: for example, e-book readers paginate content, but are interactive.

3.2. Expanding Clipping Bounds: the overflow-clip-margin property