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:
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
).
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
negative 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
end
-side of the
scrollable overflow rectangle
as necessary to enable a scroll position
that satisfies the requirements of
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 the end,
there is padding between the end-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.
Issue: Replace this image with a proper SVG.
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
negative scrollable overflow region
(thereby behaving as if they had no
scrollable overflow
on the wrong side of the
scroll origin
).
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.
A box’s
overflow
can be visible or clipped.
CSS also allows a box to be
scroll container
that allows the user to scroll clipped parts of its
scrollable overflow area
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
However, the
align-content
and
justify-content
properties
[CSS-ALIGN-3]
can be used to change the
initial scroll position
see
CSS Box Alignment 3
§ 5.3 Overflow and Scroll Positions
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.)
The area beyond the
scroll origin
in either axis
is considered the
negative scrollable overflow region
content rendered here is not accessible to the reader,
see
§ 2.2 Scrollable Overflow
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
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
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
visible
clip
values of
overflow
compute to
auto
hidden
(respectively)
if one of
overflow-x
or
overflow-y
is neither
visible
nor
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
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
As mentioned in
CSS Backgrounds 3
§ 4.3 Corner Clipping
the clipping region established by
overflow
can be rounded:
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
This property defines the
overflow clip edge
of the box,
i.e. precisely
how far
outside its bounds
the box’s content is allowed to paint
before being clipped
by effects (such as
overflow: clip
, above)
that are defined to clip to the box’s
overflow clip edge
Values are defined as follows:

Specifies the box edge to use as the
overflow clip edge
origin,
i.e. when the specified offset is zero.
If omitted,
defaults to
padding-box

The specified offset dictates
how much the
overflow clip edge
is expanded from
the specified box edge
Negative values are invalid.
Defaults to zero if omitted.
The
overflow clip edge
is shaped in the corners
exactly the same way as an
outer box-shadow
with a spread radius of the same cumulative offset
from the box’s
border edge
See
CSS Backgrounds 3
§ 4.2 Corner Shaping
and
CSS Backgrounds 3
§ 6.1.1 Shadow Shape, Spread, and Knockout
noting in particular the formula for outsets beyond the
border edge
Note:
This property has no effect on boxes
with
overflow: hidden
or
overflow: scroll
which are not defined to use the
overflow clip edge
3.3.
Overflow Viewport Propagation
UAs must apply the
overflow-*
values
set on the root element to the
viewport
when the root element’s
display
value is not
none
However,
when the root element is an
[HTML]
html
element
(including
XML syntax for HTML
whose
overflow
value is
visible
(in both axes),
and that element has as a child
body
element whose
display
value is also not
none
user agents must instead apply the
overflow-*
values
of the first such child element to the viewport.
The element from which the value is propagated must then have
a used
overflow
value of
visible
Note:
Using
containment
on the HTML
html
or
body
elements disables
this special handling of the HTML
body
element.
See the
CSS Containment 1
§ 2 Strong Containment: the contain property
for details.
Note:
overflow: hidden
on the root element
might not clip everything outside the
Initial Containing Block
if the ICB is smaller than the viewport,
which can happen on mobile.
If
visible
is applied to the viewport,
it must be interpreted as
auto
If
clip
is applied to the viewport,
it must be interpreted as
hidden
The
scroll-behavior
property specifies the scrolling behavior for a
scroll container
when scrolling happens due to navigation,
scrolling APIs
[CSSOM-VIEW]
or scroll snapping operations not initiated by the user
[CSS-SCROLL-SNAP-1]
Any other scrolls, e.g. those that are performed by the user, are not affected by this property.
When this property is specified on the root element, it applies to the
viewport
instead.
Note:
The
scroll-behavior
property of the HTML
body
element is
not
propagated to the viewport.
auto
The
scroll container
is scrolled in an
instant
fashion.
smooth
The
scroll container
is scrolled in a
smooth
fashion
using a user-agent-defined timing function over a user-agent-defined period of time.
User agents should follow platform conventions, if any.
User agents may ignore this property.
When reserving space for a scrollar placed at the edge of an element’s box,
the reserved space is inserted between the inner border edge
and the outer padding edge.
For the purpose of the
background positioning area
and
background painting area
however,
this reserved space is considered to be part of the
padding box
In the following document fragment,
both an absolutely-positioned element
and a background image
are positioned to the top right of the box.
style
article
background
top
right
no-repeat
url
circle.png
);
position
relative
overflow
auto
aside
position
absolute
top
right
style
article
aside
aside
article
If no scrollbars are present on