CSS Basic User Interface Module Level 4
CSS Basic User Interface Module Level 4
W3C Working Draft
6 April 2026
More details about this document
This version:
Latest published version:
Editor's Draft:
Previous Versions:
History:
Implementation Report:
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
Florian Rivoal
On behalf of Bloomberg
Tab Atkins-Bittner
Google
Suggest an Edit for this Spec:
GitHub Editor
Test Suite:
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
Abstract
This specification describes user interface related
properties and values to style HTML and XML (including XHTML).
It includes and extends user interface related features
from the properties and values of previous CSS levels.
It uses various properties and values
to style basic user interface elements in a document.
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 section describes the status of this document at the time of its publication.
A list of current W3C publications
and the latest revision of this technical report
can be found in the
W3C standards and drafts index.
This document was published
by the
CSS Working Group
as a
Working Draft
using the
Recommendation
track
Publication as a Working Draft
does not imply endorsement by
W3C
and its Members.
This is a draft document
and may be updated, replaced
or obsoleted by other documents at any time.
It is inappropriate to cite this document as other than a work in progress.
Please send feedback
by
filing issues in GitHub
(preferred),
including the spec code “css-ui” in the title, like this:
“[css-ui]
…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
This document was produced by a group operating under the
W3C Patent Policy
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of the group;
that page also includes instructions for disclosing a patent.
An individual who has actual knowledge of a patent that the individual believes
contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy
This specification will include and extend
CSS Basic User Interface Module Level 3.
[CSS-UI-3]
The following features are at-risk, and may be dropped during the CR period:
Applicability of
user-select
to
::before
and
::after
“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
This module describes CSS properties which enable authors
to style user interface related properties and values.
Section 2.1 of CSS1
[CSS1]
and
Chapter 18 of CSS2
[CSS21]
introduced several user interface related properties and values.
User Interface for CSS3 (16 February 2000)
introduced several new user interface related features.
[CSS-UI-3]
was later introduced to incorporate, extend, and supersede these.
This specification continues this work, and in turn replaces
[CSS-UI-3]
1.1.
Purpose
The purpose of this specification is to achieve the following objectives:
Extend the user interface features in
[CSS21]
and
[CSS-UI-3]
Provide additional CSS mechanisms to augment or replace other
dynamic presentation related features in HTML.
Introduce directional navigation properties to assist in the construction of
user interfaces which make use of a directional navigation model.
2.
Module Interactions
This document defines new features not present in earlier specifications.
In addition, it replaces and supersedes
[CSS-UI-3]
which itself replaced and superseded the following:
Section 18.1
section 18.4
and Information on the stacking of outlines defined in
Appendix E
of Cascading Style Sheets, level 2, revision 1
[CSS21]
User Interface for CSS3 (16 February 2000)
[CSS-UI-3]
Note:
The
box-sizing
property was previously defined in this section of the specification,
but has been moved to
CSS Sizing 3
§ 3.3 Box Edges for Sizing: the box-sizing property
Note:
The
text-overflow
property was previously defined in this section of the specification,
but has been moved to
CSS Overflow 3
§ 5.1 Overflow Ellipsis: the text-overflow property
2.1.
Value Definitions
This specification follows the
CSS property definition conventions
from
[CSS21]
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.
3.
Outline properties
At times, style sheet authors may want to create outlines around
visual objects such as buttons, active form fields, image maps, etc.,
to make them stand out. Outlines differ from borders in the following
ways:
Outlines do not take up space.
Outlines contribute to the
ink overflow area
of an element.
Outlines may be non-rectangular.
UAs often render outlines on elements in the
:focus-visible
state.
The outline properties control the style of these dynamic outlines.
The stacking of the rendering of these outlines is explicitly left up to implementations
to provide a better user experience per platform.
This supersedes the stacking of outlines as defined in
Appendix E of CSS 2.1
[CSS21]
Keyboard users,
in particular people with disabilities
who may not be able to interact with the page in any other fashion,
depend on the outline being visible
on elements in the
:focus-visible
state,
thus authors must not make the outline invisible on such elements
without making sure an alternative highlighting mechanism is provided.
The rendering of applying transforms to outlines is left explicitly undefined.
3.1.
Outlines Shorthand: the
outline
property
Name:
outline
Value:
<'outline-width'>
||
<'outline-style'>
||
<'outline-color'>
Initial:
see individual properties
Applies to:
all elements
Inherited:
no
Percentages:
N/A
Computed value:
see individual properties
Animation type:
see individual properties
Canonical order:
per grammar
The
outline
property is a shorthand property
and sets all three of
outline-style
outline-width
and
outline-color
In the ambiguous case where
a lone
auto
value is specified,
or if
auto
is specified together with an
<'outline-width'>
value,
but without an explicit
<'outline-style'>
or
<'outline-color'>
value,
both
outline-style
and
outline-color
are set to
auto
Note:
The shorthand purposefully omits the
outline-offset
property,
which determines the position rather than the appearance of the outline,
so that it can cascade independently,
as well as for backwards compatibility reasons.
The outline created with the outline properties is drawn "over" a box,
i.e., the outline is always on top
and doesn’t influence the position or size of the box,
or of any other boxes.
Therefore, displaying or suppressing outlines does not cause reflow.
Outlines may be non-rectangular.
For example, if the element is broken across several lines,
the outline should be an outline or minimum set of outlines
that encloses all the element’s boxes.
Each part of the outline should be fully connected
rather than open on some sides
(as borders on inline elements are when lines are broken).
The parts of the outline are not required to be rectangular.
To the extent that the outline follows the
border edge
it should follow the
border-radius
curve,
as well as the
corner-shape
The position of the outline may be affected by descendant boxes.
The dimensions of the drawn outline contribute to the
ink overflow area
of an element.
User agents should use an algorithm for determining
the outline that encloses a region appropriate
for conveying the concept of focus to the user.
Note:
This specification does not define the exact position or shape of the outline, but it is typically drawn immediately outside the border box.
Note:
The outline is the same on all sides.
In contrast to borders,
there are no
outline-top
outline-left
, etc. properties.
This specification does not define how multiple overlapping outlines are drawn
or how outlines are drawn for boxes that are partially obscured behind other elements.
Here’s an example of drawing a thick outline around a BUTTON element:
button
outline
thick solid
Graphical user interfaces may use outlines around elements
to tell the user which element on the page has the focus.
These outlines are shown in addition to any borders,
and switching outlines on and off should not cause the document to reflow.
The focus is the subject of user interaction in a document
(e.g. for entering text or selecting a button).
For example, to draw a thick black line around elements in the
:focus-visible
state, and a thick red line when it is in the
:active
state, the following rules can be used:
:focus-visible
outline
thick solid black
:active
outline
thick solid red
Note:
Since the outline does not affect formatting
(i.e., no space is left for it in the box model),
it may well overlap other elements on the page.
3.2.
Outline Thickness: the
outline-width
property
Name:
outline-width
Value:
Initial:
medium
Applies to:
all elements
Inherited:
no
Percentages:
N/A
Computed value:
absolute length,
snapped as a border width
Canonical order:
per grammar
Animation type:
by computed value
The
outline-width
property accepts
the same values as
border-width
CSS Backgrounds 3
§ 3.3 Line Thickness: the border-width properties
),
with the same meaning.
3.3.
Outline Patterns: the
outline-style
property
Name:
outline-style
Value:
auto
Initial:
none
Applies to:
all elements
Inherited:
no
Percentages:
N/A
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
by computed value
accepts
the same values as
CSS Backgrounds 3
§ 3.2 Line Patterns: the border-style properties
with the same meaning,
except that
hidden
is not a legal outline style.
In addition,
the
outline-style
property
accepts the value
auto
The
auto
value permits the user agent
to render a custom outline style,
typically a style which is either a user interface default for the platform,
or perhaps a style that is richer
than can be described in detail in CSS,
e.g. a rounded edge outline with semi-translucent outer pixels
that appears to glow.
User agents may enable authors to influence the rendering of
auto
style outlines
via the
outline-color
property,
but this specification does not define how the rendering is impacted (if at all).
The
outline-width
property is ignored when
outline-style
is
auto
User agents may treat
auto
as
solid
3.4.
Outline Colors: the
outline-color
property
Name:
outline-color
Value:
auto
<'border-top-color'>
Initial:
auto
Applies to:
all elements
Inherited:
no
Percentages:
N/A
Computed value:
see below
Canonical order:
per grammar
Animation type:
by computed value
The
outline-color
property
accepts all values of
<'border-top-color'>
as well as the following keywords:
auto
When
outline-style
is
auto
outline-color: auto
computes to
auto
and represents the
accent color
Otherwise,
outline-color: auto
computes to
currentColor
See
CSS Color 4
§ 15. Resolving
for the computed value of
values,
and
CSS Images 4
§ 4 1D Image Values: the
for
values.
Earlier versions of this specification had an additional
invert
value,
performing a color inversion on the pixels on the screen.
This is no longer supported,
and was removed for lack of implementations
(and of intent to implement)
in modern user agents.
See
CSS User Interface 3
§ 4.4 Outline Colors: the outline-color property
for details.
3.5.
Offsetting the Outline: the
outline-offset
property
By default, the outline is drawn starting just outside the
border edge
However, it is possible to offset the outline and draw it beyond the
border edge
Name:
outline-offset
Value:
Initial:
Applies to:
all elements
Inherited:
no
Percentages:
N/A
Computed value:
absolute length
Canonical order:
per grammar
Animation type:
by computed value
If the computed value of
outline-offset
is anything other than 0,
then the outline is outset from the
border edge
by that amount.
For example,
to leave 2 pixels of space between a focus outline
and the element that has the focus or is active,
the following rule can be used:
:focus
:active
outline-offset
px
Negative values must cause the outline
to shrink into the border box.
Both the height and the width of the outside of the shape
drawn by the outline should not become smaller
than twice the computed value of the
outline-width
property
to make sure that an outline can be rendered
even with large negative values.
User agents should apply this constraint
independently in each dimension.
If the outline is drawn as multiple disconnected shapes,
this constraint applies to each shape separately.
4.
Resizing
CSS2.1 provides a mechanism for controlling the appearance of a scrolling mechanism
(e.g. scrollbars)
on block container elements.
This specification adds a mechanism to that for controlling
user resizability of elements as well as the ability to specify text overflow behavior.
4.1.
Resizing Boxes: the
resize
property
The
resize
property allows the author
to specify whether or not an element is resizable by the user,
and if so, along which axis/axes.
Name:
resize
Value:
none
both
horizontal
vertical
block
inline
Initial:
none
Applies to:
elements that are
scroll containers
and optionally replaced elements such as images, videos, and iframes
Inherited:
no
Percentages:
N/A
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
discrete
none
The UA does not present a resizing mechanism on the element,
and the user is given no direct manipulation mechanism to resize the element.
both
The UA presents a bidirectional resizing mechanism
to allow the user to adjust both the height and the width of the element.
horizontal
The UA presents a unidirectional horizontal resizing mechanism
to allow the user to adjust only the width of the element.
vertical
The UA presents a unidirectional vertical resizing mechanism
to allow the user to adjust only the height of the element.
block
The UA presents a unidirectional
block-axis
resizing mechanism
to allow the user to adjust only the
block size
of the element.
inline
The UA presents a unidirectional
inline-axis
resizing mechanism
to allow the user to adjust only the
inline size
of the element.
Currently it is possible to control the appearance of the scrolling mechanism (if any)
on an element using the
overflow
property
(e.g.
overflow
scroll
vs.
overflow
hidden
etc.).
The purpose of the
resize
property
is to allow control over the appearance and function of the resizing mechanism
(e.g. a resize box or widget) on the element.
Note:
The resizing mechanism is NOT the same as the scrolling mechanism,
nor is it related to any UA mechanism for zooming.
The scrolling mechanism allows the user
to determine which portion of the contents of an element is shown.
The resizing mechanism allows the user
to determine the size of the element.
The
resize
property applies to elements
that are
scroll containers
UAs may also apply it,
regardless of the value of the
overflow
property,
to:
Replaced elements representing images or videos,
such as
img
video
picture
svg
object
, or
canvas
The
iframe
element.
The effect of the
resize
property on generated content is undefined.
Implementations should not apply the
resize
property to generated content.
Note:
The
resize
property may apply to generated content in the future
if there is implementation of
Interface CSSPseudoElement
When an element is resized by the user,
the user agent sets
the
width
and
height
properties
to px unit length values of the size indicated by the user
in the element’s
style attribute
DOM,
replacing existing property declaration(s), if any,
without
!important
, if any.
If an element is resized in only one dimension,
only the corresponding property is set, not both.
The precise direction of resizing
(i.e. altering the top-left of the element or altering the bottom-right)
may depend on a number of CSS layout factors,
including whether the element is absolutely positioned,
whether it is positioned using the
right
and
bottom
properties,
whether the language of the element is right-to-left etc.
The UA should consider the direction of resizing
(as determined by CSS layout),
as well as platform conventions and constraints,
when deciding how to convey the resizing mechanism to the user.
The user agent must allow the user to resize the element
with no other constraints than what is imposed by
min-width
max-width
min-height
, and
max-height
Note:
There may be situations in which user attempts to resize an element
appear to be overridden or ignored, e.g. because of
!important
cascading declarations that supersede
that element’s
style attribute
width
and
height
properties in the DOM.
Changes to the computed value of an element’s
resize
property
do not reset changes to the
style attribute
made due to
user resizing of that element.
For example,
to make iframes scrollable
and
resizable,
the following rule can be used:
iframe
object
type^=
"text/"
],
object
type$=
"+xml"
],
object
type=
"application/xml"
overflow
auto
resize
both
5.
Pointing Devices and Keyboards
5.1.
Pointer interaction
5.1.1.
Styling the Cursor: the
cursor
property
Name:
cursor
Value:
Initial:
auto
Applies to:
all elements
Inherited:
yes
Percentages:
N/A
Computed value:
as specified, except with any relative URLs converted to absolute
Canonical order:
per grammar
Animation type:
discrete
This property specifies the type of cursor to be displayed for the pointing device
when the cursor’s hotspot is within the element’s
border edge
Note:
As per
CSS Backgrounds 3
§ 4.1 Curve Radii: the border-radius properties
, the
border edge
is affected by
border-radius
In the case of overlapping elements,
which element determines the type of cursor
is based on hit testing:
the element determining the cursor
is the one that would receive a click
initiated from this position.
Note:
The specifics of hit testing
are out of scope of this specification.
Hit testing will hopefully be defined
in a future revision of CSS or HTML.
User agents may ignore the cursor property
over native user agent controls such as scrollbars, resizers, or other native UI widgets
e.g. those that may be used inside some user agent specific implementations of form elements.
User agents may also ignore the
cursor
property
and display a cursor of their choice
to indicate various states of the UA’s user interface,
such as a busy cursor when the page is not responding,
or a text cursor when the user is performing text selection.
Note:
[HTML]
defines
special handling of image maps
for the
cursor
property.
Values have the following meanings:
The first (optional) component of the
cursor
property
is a list of image-based cursors.
If the user agent cannot handle the first cursor of a list of cursors,
it must attempt to handle the second, etc.
If the user agent cannot handle any of these author-defined cursors,
it must use the keyword-based cursor at the end of the list.
has the following syntax:
= [
{2}
The user agent retrieves the cursor from the resource designated by the
or
Conforming user agents may, instead of
and
support
which is a superset.
is a limited version of
image-set()
where the
sub-production is restricted to
only.
The UA must support the following image file formats:
PNG, as defined in
[PNG]
SVG, as defined in
[SVG11]
in
secure static mode
[SVG2]
if it has a
natural size
any other non-animated image file format that they support
for
in other properties,
such as the
background-image
property
In addition, the UA should support the following image file formats:
SVG, as defined in
[SVG11]
in
secure animated mode
[SVG2]
if it has a
natural size
any other animated image file format that they support
for
in other properties,
such as the
background-image
property
The UA may also support additional file formats,
including SVG, as defined in
[SVG11]
in secure static mode or secure animated mode
[SVG2]
even if it does not have a
natural size
Note:
The CSS Working Group initially intended support for all SVG,
naturally sized or not.
Support for non-naturally sized SVG was downgraded from mandatory to optional due
to a lack of implementations.
Note:
For a number of years,
the only file formats supported for cursors in common desktop browsers were
the .ico and .cur file formats, as designed by Microsoft.
Although this is no longer the case
(PNG and SVG have broad support),
for compatibility with legacy content,
UAs are encouraged to support these,
even though the lack of an open specification
makes it impossible to have a normative requirement
about these formats.
Some information on these formats can be found
on Wikipedia
The
default object size
for cursor images is
a UA-defined size that should be based on
the size of a typical cursor on the UA’s operating system.
The
concrete object size
is determined using
the
default sizing algorithm
If an operating system is
incapable
of rendering a cursor above a given size,
cursors larger than that size must be shrunk to within
the OS-supported size bounds,
while maintaining the cursor image’s
natural aspect ratio
, if any.
The optional pair of
values
give the X and Y coordinates
of the exact position within the image which is the pointer position (i.e., the hotspot),
as offsets from the left/top of the image.
Note:
This specification does not define
how the coordinate systems of the various types of
are established,
and defers these definitions to
[CSS4-IMAGES]
If the values are omitted,
then the natural hotspot defined inside the image resource itself is used.
If it has no natural hotspot,
the top left corner of the image is used,
as if
0 0
were provided.
If the X or Y coordinates of the hotspot
(whether specified explicitly or taken from the image)
fall outside of the cursor image,
they must be clamped (independently) to fit.
The mandatory
keyword
specifies a predefined cursor to use,
or the
fallback
cursor to be used
if
s were provided
and none of them can be successfully used.
See
§ 5.1.1.1 Predefined Cursors
for the full set of
keywords
and their meanings.
Here is an example of using several cursor values.
:link
:visited
cursor
url
example.svg
),
url
hyper.cur
),
url
hyper.png
pointer
This example sets the cursor on all hyperlinks (whether visited or not)
to an external SVG image to be used as a cursor.
If that fails to load, user agents would simply skip
to the next value and attempt to use the "hyper.cur" cursor.
If that cursor format was also not supported,
the UA could attempt to use the "hyper.png" cursor with the explicit hotspot.
Finally, if the UA cannot load any of those image cursors, the UA would skip to the last value
and render the
pointer
cursor.
5.1.1.1.
Predefined Cursors
The
production encompasses a broad selection of predefined cursors,
present on most operating systems.
Its syntax is:
= auto
default
none
context-menu
help
pointer
progress
wait
cell
crosshair
text
vertical-text
alias
copy
move
no-drop
not-allowed
grab
grabbing
e-resize
n-resize
ne-resize
nw-resize
s-resize
se-resize
sw-resize
w-resize
ew-resize
ns-resize
nesw-resize
nwse-resize
col-resize
row-resize
all-scroll
zoom-in
zoom-out
The
keywords have the following meanings
and likely renderings:
general purpose cursors
auto
The UA determines the cursor to display based on the current context:
auto
behaves as
text
over selectable text or editable elements,
and
default
otherwise.
default
The platform-dependent default cursor. Often rendered as an arrow.
none
No cursor is rendered for the element.
links and status cursors
context-menu
A context menu is available for the object under the cursor.
Often rendered as an arrow with a small menu-like graphic next to it.
help
Help is available for the object under the cursor.
Often rendered as a question mark or a balloon.
pointer
The cursor is a pointer that indicates a link.
progress
A progress indicator. The program is performing some processing,
but is different from
wait
in that the user may still interact
with the program. Often rendered as a spinning beach ball,
or an arrow with a watch or hourglass.
wait
Indicates that the program is busy and the user should wait.
Often rendered as a watch or hourglass.
selection cursors
cell
Indicates that a cell or set of cells may be selected. Often rendered as a thick plus-sign with a dot in the middle.
crosshair
A simple crosshair (e.g., short line segments resembling a "+" sign).
Often used to indicate a two dimensional bitmap selection mode.
text
Indicates text that may be selected. Often rendered as a vertical I-beam.
User agents may automatically display a horizontal I-beam/cursor
(e.g. same as the
vertical-text
keyword)
for vertical text, or for that matter,
any angle of I-beam/cursor for text that is rendered at any particular angle.
vertical-text
Indicates vertical-text that may be selected. Often rendered as a horizontal I-beam.
drag and drop cursors
alias
Indicates an alias of/shortcut to something is to be created.
Often rendered as an arrow with a small curved arrow next to it.
copy
Indicates something is to be copied.
Often rendered as an arrow with a small plus sign next to it.
move
Indicates something is to be moved.
no-drop
Indicates that the dragged item cannot be dropped at the current cursor location.
Often rendered as a hand or pointer with a small circle with a line through it.
not-allowed
Indicates that the requested action will not be carried out.
Often rendered as a circle with a line through it.
grab
Indicates that something can be grabbed (dragged to be moved).
Often rendered as the backside of an open hand.
grabbing
Indicates that something is being grabbed (dragged to be moved).
Often rendered as the backside of a hand with fingers closed mostly out of view.
resizing and scrolling cursors
e-resize
n-resize
ne-resize
nw-resize
s-resize
se-resize
sw-resize
w-resize
Indicates that some edge is to be moved. For example, the
se-resize
cursor is used when the movement starts from the
south-east corner of the box.
ew-resize
ns-resize
nesw-resize
nwse-resize
Indicates a bidirectional resize cursor.
col-resize
Indicates that the item/column can be resized horizontally.
Often rendered as arrows pointing left and right with a vertical bar separating them.
row-resize
Indicates that the item/row can be resized vertically.
Often rendered as arrows pointing up and down with a horizontal bar separating them.
all-scroll
Indicates that the something can be scrolled in any direction.
Often rendered as arrows pointing up, down, left, and right with a dot in the middle.
zooming cursors
zoom-in
zoom-out
Indicates that something can be zoomed (magnified) in or out, and
often rendered as a magnifying glass with a "+" or "-" in the center of the glass, for
zoom-in
and
zoom-out
respectively.
5.1.1.2.
Cursor of the canvas
The document
canvas
is the infinite surface over which the document is rendered
[CSS21]
Since no element corresponds to the canvas,
in order to allow styling of the cursor when not over any element,
the canvas cursor re-uses the root element’s cursor.
However, if no boxes are generated for the root element
(for example, if the root element has
display: none
),
then the canvas cursor is the platform-dependent default cursor.
Note:
An element might be invisible
but still generate boxes. For example,
if the element has
visibility: hidden
but not
display: none
boxes are generated for it and its cursor is used for the canvas.
5.2.
Insertion caret
The
insertion caret
(or “caret” for short)
is a visible indicator of the insertion point in an element that
accepts text input
where text (and potentially other content) can be inserted by the user.
The
caret-color
caret-animation
, and
caret-shape
properties
give the author some amount of control over the appearance of the
caret
Text or elements are considered to
accept text input
if they are either an
editable element
or a descendent thereof,
excluding any such element where the
used value
of
user-select
is
none
as well as subtrees rooted at an HTML element with a
contentEditable
attribute set to
false
Some user agents have other user interface mechanisms
with a similar appearance,
also occasionally referred to as “carets”.
For example, some UAs can show a “navigation caret”,
which acts similarly to an
insertion caret
but can be moved around in non-editable text.
The
caret-color
caret-animation
, and
caret-shape
properties
are not intended to apply to such mechanisms
nor outside of
editable elements
though user agents may choose to take them into account.
Whether to do so and to what extent is up to the user agent.
Note:
The cursor image shown
when hovering over text when the
cursor
property is
auto
or when hovering over an element where the
cursor
property is
text
or
vertical-text
though it sometimes resembles a caret,
is not a caret (it’s a cursor).
Within the context of this section,
character
is
to be understood as
extended grapheme cluster
as defined in
[UAX29]
, and
visible character
means a character with a non-zero advance measure.
5.2.1.
Coloring the Insertion Caret: the
caret-color
property
Name:
caret-color
Value:
auto
[auto
Initial:
auto
Applies to:
text or elements that
accept text input
Inherited:
yes
Percentages:
N/A
Computed value:
The computed value for
auto
is
auto
For
values, see
CSS Color 4
§ 15. Resolving
Canonical order:
per grammar
Animation type:
by computed value
This property controls the color of the
insertion caret
It takes one or two values.
The first value has the following effects:
auto
User agents should use
currentColor
User agents may automatically adjust the color of
caret
to ensure good visibility and contrast with the surrounding content,
possibly based on the currentColor, background, shadows, etc.
Note:
When
caret-shape
is
block
ensuring good visibility and contrast
is best achieved with a UA-determined color other than
currentColor
The
caret
is colored with the specified color.
Example: a textarea with
caret-color
#00aacc
The second value has no effect when
caret-shape
is
bar
underscore
or
auto
behaving as either of these values.
If
caret-shape
is
block
—or
auto
behaving as
block
—then it determines the color of the text
overlapping the caret
If the second value is omitted,
the behavior is the same as if
auto
had been specified.
auto
User agents must automatically adjust the color of the text
overlapping the caret
to ensure good visibility and contrast between the text
and the underlying
block
caret,
if using
currentColor
would result in poor readability.
The specifics of how to assess contrast
and how to pick a sufficiently contrasty color are up to the user agent.
The color of text
overlapping the caret
is the specified color.
Note:
Authors wishing to ensure that the color of the text remains constant
regardless of the position of a
block
caret
can specify
currentColor
as the second value of
caret-color
Text considered to
overlap the caret
is the next
visible character
after the insertion point, if any.
This illustrates the effect of the second value of
caret-color
on
block
carets.
In each of the sample renderings below,
the insertion point is between the letters u and m.
'caret-color:'
Sample rendering
Your browser
(focus each cell to see the
caret
black
(or
black auto
Lorem ipsu
Lorem Ipsum
black yellow
Lorem ipsu
Lorem Ipsum
black black
Lorem ipsu
Lorem Ipsum
Optionally, user agents may treat as overlapping only those parts of next
visible character
which visually intersect with the
block
and adjust the color of those parts only.
5.2.2.
Animation of the insertion caret:
caret-animation
Name:
caret-animation
Value:
auto
manual
Initial:
auto
Applies to:
text or elements that
accept text input
Inherited:
yes
Percentages:
N/A
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
discrete
On most platforms and in most UAs,
the
insertion caret
blinks.
This property allows the author
to take control over the way the
caret
is animated.
auto
The UA determines how the
caret
should be animated, if at all,
as well as the speed of any such animation.
It should match platform conventions and settings,
and may be adjusted based on context.
Note:
This is typically rendered as a blinking
caret
Fading in and out instead of blinking is a variant that appears in some environments.
manual
The UA must not animate the
caret
Note:
This is only about UA-driven animations of the
caret
When CSS animations are used to animate the
caret
color,
they apply normally.
Note:
It is recommended for authors to stop the
caret
from blinking or fading
using
caret-animation: manual
when applying custom animations using
[CSS3-ANIMATIONS]
to prevent the UA’s animation and the CSS animation to interfere.
Note:
See
Guideline 2.3: Seizures: Do not design content in a way that is known to cause seizures
[WCAG20]
A user who is disturbed by or has adverse reactions to blinking or flashing visuals
may want to make all
carets
static and non-blinking,
regardless of platform defaults or author settings.
This can be accomplished with the following rule in the user stylesheet.
/* prevent the caret from blinking/flashing */
:read-write
caret-animation
manual !important
/* prevent changes of caret-color, including animations */
:read-write
caret-color
auto !important
UAs that do not have an editable user stylesheet
should provide a setting to disable
blinking
flashing
and animated
carets
UAs that do have an editable user stylesheet may want to provide this setting as well.
See
[WCAG]
Guideline 2.2
and
Guideline 2.3
for details.
Typically, the
caret
blinks on and off.
This makes it alternate between 2 colors.
textarea
caret-animation
manual
caret-color
blue
animation
caret-alternate
step-end infinite
@keyframes
caret-alternate
50
caret-color
red
The simulated rendering below illustrates how this is expected to look.
Text area
with color-alternating caret
Focus the element below to see how your browser renders it.
Text area with color-alternating caret
If a user agent is unwilling to yield control of
caret
animations
to page authors and would not honor
caret-animation: manual
it must not implement the property at all.
Note:
This enables authors to use
@supports
caret-animation: manual
to gate code that would depend on this functionality.
See
[CSS-CONDITIONAL-3]
5.2.3.
Shape of the insertion caret:
caret-shape
Name:
caret-shape
Value:
auto
bar
block
underscore
Initial:
auto
Applies to:
text or elements that
accept text input
Inherited:
yes
Percentages:
N/A
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
by computed value
This property allows authors to specify
the desired shape of the
insertion caret
auto
The UA determines the shape of the
caret
It should match platform conventions,
and may be adjusted based on context.
For example, if a UA switches between insert mode and overtype mode when the
user presses the
insert
key on their keyboard,
it may show a
bar
caret
in insert mode,
and a
block
caret
in overtype mode.
bar
The UA must render the
insertion caret
as a thin bar placed at the insertion point.
This means it is between, before, or after
characters
, not over them.
It should be perpendicular to the inline progression direction,
although UAs may render it slanted when inserting italic or oblique text.
block
The UA must render the
insertion caret
as a rectangle overlapping the next
visible character
following the insertion point.
If there is no
visible character
after the insertion point,
the UA must render the caret after the last
visible character
UAs may render it as a slanted rectangle when inserting italic or oblique text.
underscore
The UA must render the
insertion caret
as a thin line
under
(as defined in
[CSS-WRITING-MODES-3]
the next
visible character
following the insertion point.
If there is no
visible character
after the insertion point,
the UA must render the caret after the last
visible character
The width of the
block
and
underscore
carets
should be the advance measure of the next
visible character
after the insertion point,
or
1ch
if there is no next
visible character
or if this information is impractical to determine.
When determining the orientation and appearance of the
caret
UAs must take into account the
writing mode
[CSS-WRITING-MODES-3]
and must apply transformations
[CSS-TRANSFORMS-1]
If the edited text is laid out on a path,
for instance by using the SVG
textPath
element,
UAs should also account for this.
The thickness of
bar
and
underscore
carets
—as well as that of
auto
carets
with a similar rendering—is determined by the user agent.
When practical, the user agent should choose a thickness that ensures
the
caret
remains visible even if it has been scaled down
via means such as transformations
[CSS-TRANSFORMS-1]
When there is not enough room at the end of a line
to display the caret positioned there,
the user agents should still display it,
even if that means means painting
past the bounds of the
scrollable overflow area
user agents may impose limits on this and clip as necessary.
User agents may also visually reposition a caret
in order to display it within the
scrollport
if it would otherwise be invisible.
The stacking position of the
caret
is left undefined within the following constraints:
The
caret
must not be obscured by the background of the element.
UAs must render
block
carets
so that the character it overlaps with is not obscured by the
caret
This illustrates the typical appearance of the various
caret
shapes.
In each of the sample renderings below,
the insertion point is between the letters u and m.
caret-shape
Sample rendering
Your browser
(focus each cell to see the
caret
bar
Lorem ipsu
Lorem Ipsum
block
Lorem ipsu
Lorem Ipsum
underscore
Lorem ispu
Lorem Ipsum
underscore
or
block
carets
are commonly used
in terminals and command lines,
as in this example.
.console
caret-shape
underscore
background
black
color
white
font-family
monospace
padding
ex
The simulated rendering below illustrates how this is expected to look.
user@host:css-ui-4 $ ls -a
. .. Overview.bs Overview.html
user@host:css-ui-4 $
Focus the element below to see how your browser renders it.
user@host:css-ui-4 $ ls -a
. .. Overview.bs Overview.html
user@host:css-ui-4 $
5.2.4.
Insertion caret shorthand:
caret
Name:
caret
Value:
<'caret-color'>
||
<'caret-animation'>
||
<'caret-shape'>
Initial:
auto
Applies to:
text or elements that
accept text input
Inherited:
yes
Percentages:
N/A
Computed value:
see individual properties
Animation type:
see individual properties
Canonical order:
per grammar
This property is a shorthand for setting
caret-color
caret-animation
, and
caret-shape
in one declaration.
Omitted values are set to their initial values.
This example illustrates using the various
caret
-related properties
in combination.
They are used here to simulate the appearance of the
caret
on an old phosphor computer monitor.
#old-screen
caret
block manual
animation
old-caret
infinite
/*styling of the screen omitted for brevity */
@keyframes
old-caret
from
50
caret-color
green
75
to
caret-color
transparent
The simulated rendering below illustrates how this is expected to look.
Focus the element below to see how your browser renders it.
5.3.
Keyboard control
5.3.1.
Directional Focus Navigation: the
nav-up
nav-right
nav-down
nav-left
properties
Name:
nav-up
nav-right
nav-down
nav-left
Value:
auto
[ current
root
Initial:
auto
Applies to:
all enabled elements
Inherited:
no
Percentages:
N/A
Computed value:
as specified
Canonical order:
per grammar
Animation type:
discrete
auto
The user agent automatically determines which element to navigate the focus to in response to directional navigational input.
The
value is an ID selector
[SELECT]
In response to directional navigation input corresponding to the property,
the focus is navigated to the first element in tree order matching the selector.
If this refers to the currently focused element,
the directional navigation input respective to the nav- property is ignored —
there is no need to refocus the same element.
If no element matches the selector,
the user agent automatically determines which element to navigate the focus to.
If the focus is navigated to an element
that was not otherwise focusable,
it becomes focusable
only as the result of this directional navigation,
and the
:focus
pseudo-class matches the element
while it is focused as such.
Note:
there were other options under consideration for such "not otherwise focusable" elements,
including focus to the next otherwise focusable element in the document tree
(including descendants of such a not otherwise focusable element).
Input on such other options is welcome and explicitly solicited,
especially from implementation experiences and author experience using the directional navigation properties in their content.
The
It is a
and it MUST NOT start with the underscore "_" character.
Error handling: if it does start with an underscore, "_parent" navigates to the parent frame,
"_root" is treated as
root
and other values navigate to a frame by that name if it exists.
If the specified target frame does not exist,
the parameter will be treated as the keyword
current
which means to simply use the frame that the element is in.
The keyword
root
indicates that the user agent should target the full window.
User agents for devices with directional navigation keys
respond by navigating the focus according to four respective nav-* directional navigation properties
(nav-up, nav-right, nav-down, nav-left).
This specification does not define which keys of a device are directional navigational keys.
Note:
Typical personal computers have keyboards with four arrow keys.
One possible implementation would be to use those four arrow keys for directional navigation.
For accessibility and user convenience,
user agents should allow configuration of which keys on a keyboard are used for directional navigation.
5.3.1.1.
Example: positioned buttons
Here is an example of buttons positioned in a diamond shape
whose directional focus navigation is set in such a way
to navigate the focus clockwise (or counter-clockwise) around the diamond shape
when the user chooses to navigate directionally.
button
position
absolute
button#b1
top
left
50
nav-right
#b2
nav-left
#b4
nav-down
#b2
nav-up
#b4
button#b2
top
50
left
100
nav-right
#b3
nav-left
#b1
nav-down
#b3
nav-up
#b1
button#b3
top
100
left
50
nav-right
#b4
nav-left
#b2
nav-down
#b4
nav-up
#b2
button#b4
top
50
left
nav-right
#b1
nav-left
#b3
nav-down
#b1
nav-up
#b3
Whatever markup sequence the buttons may have
(which is not specified in this example)
is irrelevant in this case because they are positioned, and yet,
it is still important to ensure focus navigation behaviors which relate reasonably to the specified layout.
5.3.1.2.
Example: moving focus to inside a frame
Moving the focus to an element in a specific frame requires both the element’s id and the frame’s name.
This example shows how to make navigating left from the button with id "foo" move the focus to the element with id "bar" within the frame named "sidebar".
button#foo
nav-left
#bar
"sidebar"
5.3.2.
Obsolete: the ime-mode property
ime-mode
is a property somewhat implemented in some browsers
that is problematic and officially obsoleted by this specification
and its predecessor
[CSS-UI-3]
User agents should not support the
ime-mode
property.
Authors must not use the ime-mode property.
Users may use the ime-mode property only for repair use cases
where they have to work around bad sites and legacy implementations,
e.g. with a user style sheet rule like:
Example: user preference
input
type=password
ime-mode
auto !important
This example CSS may be placed into a user style sheet file to force password input fields to behave in a default manner.
This specification deliberately does not attempt
to document the functionality of legacy ime-mode implementations
nor what they specifically support because it does not make sense to pursue or recommend any such path.
Note: there are several
[HTML5]
features which authors should use
to provide information to user agents that allow them to provide a better input user experience:
The global
lang
attribute
The
inputmode
pattern
, and
type
attributes of the input element
6.
User Interaction
6.1.
Controlling content selection
The
user-select
property enables authors to specify
which elements in the document can be selected by the user and how.
This allows for easier interactions when not
all elements are equally useful to select,
avoiding accidental selections of neighboring content.
Name:
user-select
Value:
auto
text
none
contain
all
Initial:
auto
Applies to:
all elements, and optionally to the
::before
and
::after
pseudo-elements
Inherited:
no
Percentages:
n/a
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
discrete
User agents must not apply the
user-select
property to
the
::first-line
and
::first-letter
pseudo-elements.
Note:
The UA may apply this property to the
::before
and
::after
pseudo-elements.
If it does, the
auto
value maps to a
used value
of
none
on these pseudos,
but other values can be specified.
This preserves the legacy behavior of generated content not being selectable or copyable,
which is appropriate when these pseudos are used for decorative purposes.
However, this property allows them to become selectable and copyable,
as the user would expect in cases where they are used to generate parts of the content,
such as the issue numbers in this document.
To the extent possible,
authors should avoid using generated content
for non-decorative purposes,
and should prefer including all the content in the DOM.
This feature is at risk.
if we allow user-select to change to a value other than
none
we need to figure out what this means for copyability and DOM APIs.
When generated content in pseudo-elements becomes selectable
through this mechanism,
UAs should also make this content findable through their search function.
Should it also apply to
::marker
? To
page-margin boxes
Should the
used value
of
auto
also be
none
or would
text
be more appropriate?
The
used value
is the same as the
computed value
except:
on
editable element
where the
used value
is always
contain
regardless of the
computed value
when the
computed value
is
auto
in which case the
used value
is one of the other values as defined below
For the purpose of this specification,
an
editable element
is either
an
editing host
or a
mutable
form control with textual content,
such as
textarea
Should there be constraints
on what happens to the used value
on elements that are editable descendants of editing hosts?
The semantics are not obvious.
Maybe
none
should map to
text
or maybe all values should map to
text
auto
The
used value
of
auto
is determined as follows:
On the
::before
and
::after
pseudo-elements,
the used value is
none
If the element is an
editable element
the
used value
is
contain
Otherwise,
if the
used value
of
user-select
on the parent of this element is
all
the
used value
is
all
Otherwise,
if the
used value
of
user-select
on the parent of this element is
none
the
used value
is
none
Otherwise, the
used value
is
text
Note:
This unusual combination of a non-inherited property with an initial value of
auto
whose used value depends on the parent element
makes it possible to create what is effectively selective inheritance.
This was initially proposed by Microsoft in IE to introduce a behavior similar to inheritance,
except that the
contain
value does not inherit.
text
The element imposes no constraint on the selection.
none
The UA must not allow selections to be started in this element.
A selection started outside of this element must not end in this element.
If the user attempts to create such a selection,
the UA must instead end the selection range at the element boundary.
Note:
As of the time of writing, experimental implementations do not all behave like this.
Firefox does.
Chrome and Safari almost do: for a selection started after the element
and trying to go backwards into the element,
they behave as specified here,
but for a selection started before the element
and trying to go into the element,
they behave as if the element has
all
and select it entirely.
IE does not restrict selections started outside of the element
from going into it at all.
Another difference is that in Chrome and Safari,
if the user attempts to start a selection inside a
user-select: none
and to end the selection out of it,
a selection will be created from the boundary of the element
to the user-designated end point.
Firefox and Internet Explorer behave as prescribed in this specification
and do not create a selection at all.
However, if this element has descendants on which the
used value
of
user-select
is not
none
selections that start and end within these descendants are allowed.
The UA must allow selections to extend across this element,
and must exclude this element from such a selection.
An exception is made for UAs which do not support multiple ranges per selection,
and they may include this element.
If the element has descendants on which the
used value
of
user-select
is not
none
these descendants must be included in a selection extending across the element.
This specification makes no normative requirement
about the behavior of the clipboard.
However, UAs are encouraged to keep the visual selection consistent
with what would get copied to the clipboard when copying.
Copying text that does not appear to be selected, or vice versa,
is highly confusing to users.
Attempting to start a selection in an element where
user-select
is
none
such as by clicking in it or starting a drag in it,
must not cause a pre-existing selection to become unselected or to be affected in any way.
As
user-select
is a UI convenience mechanism,
not a copy protection mechanism,
the UA may provide an alternative way for the user
to explicitly select the text even when
user-select
is
none
Note:
none
is not a copy protection mechanism,
and using it as such is ineffective:
user agents are allowed to provide ways to bypass it,
it will have no effect on legacy user agents that do not support it,
and the user can disable it through the user style sheet or equivalent mechanisms
on UAs that do anyway.
Instead,
none
is meant to
make it easier for the user to select the content they want
by letting the author disable selection on UI elements
that are not useful to select.
Tools such as CSS validators, linters, or in-browser developer tools
are encouraged to use heuristics
to detect and warn against incorrect or abusive usage
that would hamper usability
or violate common user expectations.
Authors should be careful about not constraining the user unnecessarily.
For example, setting
user-select: none
on the root element,
and relaxing that restriction on a handful of elements the author judges useful to select can be frustrating to users:
Clicking in empty areas to undo the current selection will no longer be effective
The author may have overlooked some areas which should be selectable
Areas may be added later to the page without remembering to make them selectable
The user may want to select pieces of text other than the main content,
for instance to look them up in a dictionary or in some translation tool,
or to look for warnings and error messages in a search engine…
Instead, a good practice is for authors is to selectively apply
user-select: none
to elements
which seem likely to be accidentally selected
when doing so would interfere with the more likely intended action.
Accidentally leaving parts of the page that are unlikely to be interacted with selectable
will likely cause much less frustration to users than the opposite.
contain
UAs must not allow a selection which is started in this element
to be extended outside of this element.
A selection started outside of this element must not end in this element.
If the user attempts to create such a selection,
the UA must instead end the selection range at the element boundary.
The UA must allow selections to extend across this element,
and such selections must include the content of the element.
Note:
At the time of writing, experimental implementations behave differently from each other
about selections started outside and selections going into the element.
The behavior can be observed even on browsers that do not explicitly support
contain
by trying to select into a
textarea
or a contenteditable element.
Note:
This was initially introduced
as an experimental feature in Internet Explorer,
under the name
user-select: element
all
The content of the element must be selected atomically:
If a selection would contain part of the element,
then the selection must contain the entire element including all its descendants.
If the element is selected
and the
used value
of
user-select
on its parent is
all
then the parent must be included in the selection, recursively.
If this element has descendants on which the
used value
of
user-select
is not
all
and if a selection is entirely contained in these descendants,
then the selection is not extended to include this whole element.
Note:
Selections can include more than just text and extend over images, tables, videos, etc.
The behavior when copying and pasting such selections is out of scope for this specification.
The following additions are made to the UA stylesheet for HTML:
button
meter
progress
select
user-select
none
the list above is incomplete and needs to include
at least the various button-like variants of
input
For compatibility with legacy content,
UAs that support
user-select
must also support
-webkit-user-select
as an alias.
Note:
The details of the aliasing mechanism is intentionally left up to the UA.
Making
-webkit-user-select
a shorthand property of
user-select
is known to be an effective approach,
and new implementers should consider it.
However, UAs supporting
-webkit-user-select
as an alias of
user-select
through other means exist
without adverse consequences to compatibility,
so this specification allows flexibility.
6.2.
Exclusion from Hit-testing: the
pointer-events
property
While this property modifies the normal behavior of hit-testing,
this normal
hit-testing
is currently not specified.
There is broad interoperability about the seemingly obvious parts of this problem,
but there are countless nuances and corner cases that would greatly benefit
from a detailed specification.
The CSS-WG would hugely appreciate
help with writing such a specification.
Name:
pointer-events
Value:
auto
none
Initial:
auto
Applies to:
all elements
Inherited:
yes
Percentages:
N/A
Computed value:
specified keyword
Canonical order:
per grammar
Animation type:
by computed value type
The
pointer-events
property defines whether an element’s boxes can be targeted by point pointer events.
Values have the following meanings:
auto
Hit-testing
occurs normally.
none
Hit-testing
acts as if the boxes generated by the element
(see
[CSS-DISPLAY-3]
were not there,
effectively causing the element behind the
pointer-events: none
element
to become the target of hit-testing-based events instead.
The statement above needs to be qualified;
for some purposes,
hit-testing continues to take the element into account.
For instance, clicking and dragging to start a text selection will continue to work as usual.
What is the precise set of things for which hit-testing is affected by
pointer-events
pointer-events: none
does not inhibit
sequential focus navigation
Note:
This
pointer-events: none
only excludes the element itself from
hit-testing
not the whole subtree.
While this property propagates to descendants via inheritance,
pointer-events: auto
can be specified on a descendant of a
pointer-events: none
element,
and such an element will participate normally in
hit-testing
Note:
Events that target a
pointer-events: auto
descendant of a
pointer-events: none
element
can still be caught by event handlers on
pointer-events: none
ancestors
of the targeted element during the bubbling or capturing phases
(see
DOM
§ 2 Events
).
Note:
SVG 2
§ 15.6 The ‘pointer-events’ property
defines a variant of this property for SVG elements,
with more possible values.
The effect of such values outside of SVG is currently not defined.
6.3.
Preventing All Interaction: the
interactivity
property
Name:
interactivity
Value:
auto
inert
Initial:
auto
Applies to:
all elements
Inherited:
yes
Percentages:
N/A
Computed value:
as specified
Canonical order:
per grammar
Animation type:
discrete
The
interactivity
property specifies whether an element and its
flat tree
descendants
(including
text nodes
are
inert
or not.
auto
The element’s
inertness
is determined by the
host language
(This will
usually
mean the element is not
inert
.)
inert
The element is
inert
When an
element
or
text node
is
inert
Hit-testing must act as if
pointer-events
was
none
regardless of its actual value.
Text selection must act as if
user-select
was
none
regardless of its actual value.
If the
element
or
text node
is editable,
it must behave as if it was non-editable.
The
element
or
text node
should be ignored
for the purposes of find-in-page and similar searching actions.
User agents may allow the user
to override the restrictions on find-in-page and text selection.
Note:
This property allows an author to force an element
inert
but doesn’t allow making an element *non*-
inert
just deferring inertness to the host language.
For example, in HTML, while a modal dialog is being displayed,
the rest of the page is forced inert automatically,
regardless of the value of this property.
In general, host languages can make use of more information about the document
than CSS has easy access to
to determine what the best inertness behavior is for users.
Note:
Inert
nodes generally cannot be focused,
and user agents do not expose the inert nodes
to accessibility APIs or assistive technologies.
An inert subtree should not contain any content or controls
which are critical to understanding or using aspects of the page
which are not in the inert state.
Content in an inert subtree will not be perceivable by all users, or interactive.
Authors should not specify elements as inert
unless the content they represent are also visually obscured in some way.
In most cases,
authors should not specify the inert attribute on individual form controls.
In these instances, the
disabled
attribute is probably more appropriate.
The following should be inserted into the HTML stylesheet,
to ensure that top-level modal dialogs become uninert by default:
inert
interactivity
inert
dialog:modal
interactivity
auto
The
dialog:modal
selector above needs to be expanded
for any other elements that escape inertness by default.
6.4.
User Interest Delay: the
interest-delay-*
properties
Name:
interest-delay-start
interest-delay-end
Value:
normal
US