CSS Overflow Module Level 3

CSS Overflow Module Level 3
CSS Overflow Module Level 3
Editor’s Draft
14 April 2026
More details about this document
This version:
Latest published version:
Previous Versions:
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
Elika J. Etemad / fantasai
Apple
Florian Rivoal
On behalf of Bloomberg
Former Editor:
L. David Baron
Google
Suggest an Edit for this Spec:
GitHub Editor
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
Abstract
This module contains the features of CSS relating to scrollable overflow handling in visual media.
This level is focused on completing a precise specification for the existing overflow features,
including the
overflow
property and its longhands;
and the
text-overflow
property.
A few additional features introduced in support of
[CSS-CONTAIN-1]
and
[CSS-CONTAIN-2]
are also defined:
overflow: clip
and the
overflow-clip-margin
property.
CSS
is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, etc.
Status of this document
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
Please send feedback
by
filing issues in GitHub
(preferred),
including the spec code “css-overflow” in the title, like this:
“[css-overflow]
…summary of comment…
”.
All issues and comments are
archived
Alternately, feedback can be sent to the (
archived
) public mailing list
www-style@w3.org
This document is governed by the
18 August 2025 W3C Process Document
The description of
overflow
and its longhands is considered
significantly more complete and correct than previous working drafts
or than
[CSS2]
but a few questions and issues remain open.
overflow: clip
and
overflow-clip-margin
are rather new,
and lack implementation experience.
text-overflow
is stable,
is unchanged form its earlier definition in
[CSS-UI-3]
While not yet fully validated by implementation experience,
the design of
line-clamp
and its longhands is considered roughly complete.
Earlier versions of this specification included experimental new ideas
for handling overflow by creating new boxes using fragmentation.
These ideas are not abandoned; they are merely
deferred until Level 4
Work will resume on fragmented overflow once this level stabilizes completed.
The following features are at-risk, and may be dropped during the CR period:
the
max-lines
property
“At-risk” is a W3C Process term-of-art, and does not necessarily imply that the feature is in danger of being dropped or delayed. It means that the WG believes the feature may have difficulty being interoperably implemented in a timely manner, and marking it as such allows the WG to drop the feature if necessary when transitioning to the Proposed Rec stage, without having to publish a new Candidate Rec without the feature first.
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.
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
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]
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
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
For example,
scroll snapping
[CSS-SCROLL-SNAP-1]
can change the
initial scroll position
away from the
scroll origin 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
Name:
overflow-x
overflow-y
overflow-block
overflow-inline
Value:
visible
hidden
clip
scroll
auto
Initial:
visible
Applies to:
block containers
[CSS2]
, flex containers
[CSS3-FLEXBOX]
, grid containers
[CSS3-GRID-LAYOUT]
Inherited:
no
Percentages:
N/A
Computed value:
usually specified value, but see text
Canonical order:
per grammar
Animation type:
discrete
Logical property group:
overflow
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
Name:
overflow
Value:
<'overflow-block'>
{1,2}
Initial:
visible
Applies to:
block containers
[CSS2]
, flex containers
[CSS3-FLEXBOX]
, and grid containers
[CSS3-GRID-LAYOUT]
Inherited:
no
Percentages:
N/A
Computed value:
see individual properties
Animation type:
discrete
Canonical order:
per grammar
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
overflow clip edge
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
can use
display: flow-root
together with
overflow: clip
scroll
This value indicates that
the content is clipped to the
overflow clip edge
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
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
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
Name:
overflow-clip-margin
Value:

||

Initial:
0px
Applies to:
boxes to which
overflow
applies
Inherited:
no
Percentages:
n/a
Computed value:
the computed

and a

keyword
Canonical order:
per grammar
Animation type:
per computed value if the

values match; otherwise discrete
This property defines the
overflow clip edge
of the box,
i.e. precisely where 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 indicate insets, instead.
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
If the box is a
scroll container
the
overflow clip edge
is clamped to stay within the element’s
padding box
(This does not affect the
computed
or
used value
of this property.)
the
border-box
value
behaves as
padding-box
and ignores any specified offset.
Note:
This property was previously defined to only affect
overflow: clip
It now also affects
scroll containers
but only to shrink the clipping 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
3.4.
Smooth Scrolling: the
scroll-behavior
Property
Name:
scroll-behavior
Value:
auto
smooth
Initial:
auto
Applies to:
scroll containers
Inherited:
no
Percentages:
n/a
Computed value:
specified value
Canonical order:
per grammar
Animation type:
not animatable
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.
4.
Scrollbars and Layout
4.1.
Scrollbar Contributions to Sizing
The space reserved for the scrollbar is located between
the
padding area
and the
border area
of the
scroll container
box.
However, for the purpose of the
background positioning area
and
background painting area
this reserved space is treated as part of the
padding area
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