<pre class='metadata'>

Title: CSS Basic User Interface Module Level 3 (CSS3 UI)

ED: https://drafts.csswg.org/css-ui-3/

TR: https://www.w3.org/TR/css-ui-3/

Previous Version: https://www.w3.org/TR/2017/PR-css-ui-3-20171214/

Shortname: css-ui

Level: 3

Group: csswg

Status: ED

Prepare for TR: no

Work Status: completed

Editor: Tantek Çelik, Mozilla https://www.mozilla.org/, tantek@cs.stanford.edu, http://tantek.com, w3cid 1464

Editor: Florian Rivoal, On behalf of Bloomberg, http://florian.rivoal.net/, w3cid 43241

Abstract: This specification describes user interface related

properties and values that are proposed for CSS level&nbsp;3

to style HTML and XML (including XHTML).

It includes and extends user interface related features from the

properties and values of CSS level&nbsp;2 revision 1.

It uses various

properties and values to style basic user interface elements in a document.

Ignored Terms: outline-top

Ignored Terms: outline-left

Ignored Terms: ime-mode

WPT Path Prefix: css/css-ui/

Ignore MDN Failure: appearance-switching, content-selection, pointer-events-control, widget-accent

Can I Use URL: https://drafts.csswg.org/css-ui-3/

Can I Use URL: http://drafts.csswg.org/css-ui-3/

Can I Use URL: https://drafts.csswg.org/css-ui/

Can I Use URL: http://drafts.csswg.org/css-ui/

Can I Use URL: https://www.w3.org/TR/css-ui-3/

Can I Use URL: http://www.w3.org/TR/css-ui-3/

Can I Use URL: https://www.w3.org/TR/css3-ui/

Can I Use URL: http://www.w3.org/TR/css3-ui/

Ignore Can I Use URL Failure: https://drafts.csswg.org/css-ui-3/

Ignore Can I Use URL Failure: http://drafts.csswg.org/css-ui-3/

Ignore Can I Use URL Failure: https://drafts.csswg.org/css-ui/

Ignore Can I Use URL Failure: http://drafts.csswg.org/css-ui/

Ignore Can I Use URL Failure: https://www.w3.org/TR/css-ui-3/

Ignore Can I Use URL Failure: http://www.w3.org/TR/css-ui-3/

Ignore Can I Use URL Failure: https://www.w3.org/TR/css3-ui/

Ignore Can I Use URL Failure: http://www.w3.org/TR/css3-ui/

Implementation Report: https://drafts.csswg.org/css-ui-3/implementation-report

</pre>

<style>

.awesome-table td {padding:5px}

.awesome-table {color:#000;background:#fff;margin: auto;}

</style>

<pre class=link-defaults>

spec:css-overflow-3;

type:property; text:overflow

type:value;

for:overflow;

text:visible

text:clip

spec:css2; type:property

text:display

text:width

text:height

text:left

text:min-width

text:min-height

text:max-width

text:max-height

text:width

text:height

text:margin-left

text:margin-top

text:padding-bottom

text:padding-left

text:padding-right

text:padding-top

text:visibility

spec:css-backgrounds-3;

type:property;

text:background-image

text:border-bottom-width

text:border-left-width

text:border-right-width

text:border-top-width

text:border-style

text:border-width

text:border-radius;

type:type; text:<line-width>

type:value; for:border-style; text:none

spec:css-gaps-1; type:property;

text:column-rule-width

</pre>

<!-- Some of the following definitions have existing exported definitions from other specs,

but not from specs that are OK to link to from a CR -->

<pre class="anchors">

url: https://www.w3.org/TR/CSS2/box.html#border-edge; type: dfn; spec: CSS2; text: border edge

url: https://www.w3.org/TR/CSS2/visufx.html#propdef-overflow

type: property; spec: CSS2; text: overflow

type: value; spec: CSS2; text: visible; for: overflow

url: https://www.w3.org/TR/CSS2/visuren.html#position-props; type: property; spec: CSS2;

text: top

text: bottom

text: left

text: right

url: https://www.w3.org/TR/CSS2/visudet.html#the-width-property; type: value; spec: CSS2; for: width; text: auto

</pre>

<h2 id="intro">Introduction</h2>

This module describes CSS properties which enable authors

to style user interface related properties and values.

<a href="https://www.w3.org/TR/REC-CSS1#anchor-pseudo-classes">Section 2.1 of CSS1</a> [[CSS1]]

and <a href="https://www.w3.org/TR/CSS2/ui.html">Chapter 18 of CSS2</a> [[CSS2]]

introduced several user interface related properties and values.

<a href="https://www.w3.org/TR/2000/WD-css3-userint-20000216">User Interface for CSS3 (16 February 2000)</a> introduced several new user interface related features.

This specification incorporates, extends, and supersedes them.

<wpt title="Basic UI tests">

inheritance.html

</wpt>

<h3 id="purpose">Purpose</h3>

The purpose of this specification is to achieve the following objectives:

<ul>

<li>Extend the user interface features in CSS2.1.

<li>Provide additional CSS mechanisms to augment or replace other

dynamic presentation related features in HTML.

</ul>

<h2 id="interaction">Module Interactions</h2>

This document defines new features not present in earlier specifications.

In addition, it replaces and supersedes the following:

<ul>

<li><a href="https://www.w3.org/TR/CSS2/ui.html#cursor-props">Section 18.1</a>,

<a href="https://www.w3.org/TR/CSS2/ui.html#dynamic-outlines">section 18.4</a>,

and Information on the stacking of outlines defined in

<a href="https://www.w3.org/TR/CSS2/zindex.html">Appendix E</a>

of Cascading Style Sheets, level 2, revision 1 [[CSS2]]

<li><a href="https://www.w3.org/TR/2000/WD-css3-userint-20000216">User Interface for CSS3 (16 February 2000)</a>

</ul>

<h3 id="values">Value Definitions</h3>

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]

using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].

Value types not defined in this specification are defined in CSS Values &amp; 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 <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

<div class="proposed correction" id=c3>

<span class=marker>Candidate Correction 3:</span>

[[CSS-CASCADE-4]] and [[WEB-ANIMATIONS-1]] have refined how to define properties,

with precise definitions for the concepts underlying [=animation type=] and [=computed value=].

The definitions of properties throughout this specification

are updated to use this terminology.

In many cases, this is arguably editorial,

but in some it defines previously unclear or ambiguous behavior.

</div>

<h2 id="box-model">Box Model addition</h2>

<h3 id="box-sizing" caniuse="css3-boxsizing">Changing the Box Model: the 'box-sizing' property</h3>

<pre class="propdef">

Name: box-sizing

Value: content-box | border-box

Initial: content-box

Applies to: all elements that accept width or height

Inherited: no

Percentages: N/A

Computed value: specified value

Animation type: <ins cite=#c3 title="Candidate correction 3">discrete</ins>

</pre>

<wpt>

box-sizing-001.html

box-sizing-003.html

box-sizing-005.html

box-sizing-007.html

box-sizing-008.html

box-sizing-009.html

box-sizing-010.html

box-sizing-011.html

box-sizing-012.html

box-sizing-013.html

box-sizing-014.html

box-sizing-015.html

box-sizing-016.html

box-sizing-017.html

box-sizing-018.html

box-sizing-019.html

box-sizing-020.html

box-sizing-021.html

box-sizing-022.html

box-sizing-023.html

box-sizing-024.html

box-sizing-025.html

box-sizing-026.html

box-sizing-027.html

parsing/box-sizing-computed.html

parsing/box-sizing-invalid.html

parsing/box-sizing-valid.html

</wpt>

<dl dfn-type=value dfn-for=box-sizing>

<dt><dfn>content-box</dfn></dt>

<dd>This is the behavior of width and height as specified by CSS2.1.

The specified width and height (and respective min/max properties)

apply to the width and height respectively of the content box of the element.

The padding and border of the element are laid out

and drawn outside the specified width and height.</dd>

<dt><dfn>border-box</dfn></dt>

<dd>Length and percentages values for width and height (and respective min/max properties)

on this element determine the border box of the element.

That is, any padding or border specified on the element

is laid out and drawn inside this specified width and height.

The content width and height are calculated

by subtracting the border and padding widths of the respective sides

from the specified 'width'

and 'height' properties.

As the content width and height

<a href="https://www.w3.org/TR/CSS2/visudet.html#the-width-property">cannot be negative</a> ([[!CSS2]], section 10.2),

this computation is floored at 0.

Used values, as exposed for instance through getComputedStyle(), also refer to the border box.

Note: This is the behavior of width and height as commonly implemented

by legacy HTML user agents for replaced elements and input elements.

</dd>

</dl>

Note: In contrast to the length and percentage values,

the ''width/auto'' value of the 'width' and 'height' properties

(as well as other keyword values introduced by later specifications,

unless otherwise specified)

is not influenced by the 'box-sizing' property,

and always sets the size of the content box.

The following terms, whose definitions vary based on the computed value of 'box-sizing' are introduced:

<table class="data">

<thead>

<tr><th><th>''box-sizing: content-box''<th>''box-sizing: border-box''

<tbody>

<tr><th><dfn>min inner width</dfn><td>'min-width'<td>max(0, 'min-width' &minus; 'padding-left' &minus; 'padding-right' &minus; 'border-left-width' &minus; 'border-right-width')

<tr><th><dfn>max inner width</dfn><td>'max-width'<td>max(0, 'max-width' &minus; 'padding-left' &minus; 'padding-right' &minus; 'border-left-width' &minus; 'border-right-width')

<tr><th><dfn>min inner height</dfn><td>'min-height'<td>max(0, 'min-height' &minus; 'padding-top' &minus; 'padding-bottom' &minus; 'border-top-width' &minus; 'border-bottom-width')

<tr><th><dfn>max inner height</dfn><td>'max-height'<td>max(0, 'max-height' &minus; 'padding-top' &minus; 'padding-bottom' &minus; 'border-top-width' &minus; 'border-bottom-width')

</table>

The <a href="https://www.w3.org/TR/CSS2/visudet.html">Visual formatting model details</a> of [[!CSS2]] are written assuming ''box-sizing: content-box''. The following disambiguations are made to clarify the behavior for all values of 'box-sizing':

<ol>

<li>In <a href="https://www.w3.org/TR/CSS2/visudet.html#blockwidth">10.3.3</a>, the second <q>width</q> in the following phrase is to be interpreted as <a spec="css2">content width</a>: <q>If 'width' is not ''width/auto'' and 'border-left-width' + 'padding-left' + 'width' + [...]</q>

<li>In <a href="https://www.w3.org/TR/CSS2/visudet.html#abs-non-replaced-width">10.3.7</a>, <q>width</q> is to be interpreted as <a spec="css2">content width</a> in the following equation: <q>'left' + 'margin-left' + 'border-left-width' + 'padding-left' + 'width' + [...]</q>

<li>In <a href="https://www.w3.org/TR/CSS2/visudet.html#min-max-widths">10.4</a>, <q>width</q>, <q>height</q>, <q>min-width</q>, <q>max-width</q>, <q>min-height</q> and <q>max-height</q> are respectively to be interpreted as <a spec="css2">content width</a>, <a spec="css2">content height</a>, <a>min inner width</a>, <a>max inner width</a>, <a>min inner height</a> and <a>max inner height</a> in the following phrases:

<ol>

<li><q>The tentative used width is calculated [...]</q>

<li><q>If the tentative used width is greater than 'max-width', the rules above are applied again, but this time using the computed value of 'max-width' as the computed value for 'width'.</q>

<li><q>If the resulting width is smaller than 'min-width', the rules above are applied again, but this time using the value of 'min-width' as the computed value for 'width'.</q>

<li><q>Select from the table the resolved height and width values for the appropriate constraint violation. Take the max-width and max-height as max(min, max) so that min ≤ max holds true. In this table w and h stand for the results of the width and height computations [...]</q>

<li>All instances of these words in the table

<li><q>Then apply the rules under "Calculating widths and margins" above, as if 'width' were computed as this value.</q>

</ol>

<li>In <a href="https://www.w3.org/TR/CSS2/visudet.html#abs-non-replaced-height">10.6.4</a>, <q>height</q> is to be interpreted as <a spec="css2">content height</a> in the following equation: <q>'top' + 'margin-top' + 'border-top-width' + 'padding-top' + 'height' + [...]</q>

<li>In <a href="https://www.w3.org/TR/CSS2/visudet.html#min-max-heights">10.7</a>, <q>width</q>, <q>height</q>, <q>min-height</q> and <q>max-height</q> are respectively to be interpreted as <a spec="css2">content width</a>, <a spec="css2">content height</a>, <a>min inner height</a> and <a>max inner height</a> in the following phrases:

<ol>

<li><q>The tentative used height is calculated [...]</q>

<li><q>If this tentative height is greater than 'max-height', the rules above are applied again, but this time using the value of 'max-height' as the computed value for 'height'.</q>

<li><q>If the resulting height is smaller than 'min-height', the rules above are applied again, but this time using the value of 'min-height' as the computed value for 'height'.</q>

<li><q>[...] use the algorithm under Minimum and maximum widths above to find the used width and height. Then apply the rules under "Computing heights and margins" above, using the resulting width and height as if they were the computed values.</q>

</ol>

</ol>

<div class="example"><p style="display:none">Example(s):

<h4 id="box-sizing-example" class="no-num no-toc">Using box-sizing to evenly share space</h4>

This example uses box-sizing to evenly horizontally split

two divs with fixed size borders inside a div container,

which would otherwise require additional markup.

sample CSS:

<pre><code class="lang-css">

div.container {

width:38em;

border:1em solid black;

}

div.split {

box-sizing:border-box;

width:50%;

border:1em silver ridge;

float:left;

}

</code></pre>

sample HTML fragment:

<pre><code class="lang-markup">

&lt;div class="container"&gt;

&lt;div class="split"&gt;This div occupies the left half.&lt;/div&gt;

&lt;div class="split"&gt;This div occupies the right half.&lt;/div&gt;

&lt;/div&gt;

</code></pre>

demonstration of sample CSS and HTML:

<div style="width:38em; border:1em solid black"><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the left half.</div><div style="box-sizing:border-box; width:50%; border:1em silver ridge; float:left">This div should occupy the right half.</div>The two divs above should appear side by side, each (including borders) 50% of the content width of their container. If instead they are stacked one on top of the other then your browser does not support 'box-sizing'.

</div>

</div>

<h2 id="outline-props" caniuse="outline">Outline properties</h2>

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:

<ol>

<li>Outlines do not take up space.

<li>Outlines may be non-rectangular.

<li>UAs often render outlines on elements in the :focus state.

</ol>

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 <a href="https://www.w3.org/TR/CSS2/zindex.html">Appendix E of CSS 2.1</a> [[CSS2]].

<strong class="advisement">

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 state,

thus authors must not make the outline invisible on such elements

without making sure an alternative highlighting mechanism is provided.

</strong>

The rendering of applying transforms to outlines is left explicitly undefined in CSS3-UI.

<wpt>

outline-003.html

outline-004.html

outline-005.html

outline-007.html

outline-008.html

outline-009.html

outline-010.html

outline-011.html

outline-012.html

outline-013.html

outline-014.html

outline-015.html

outline-016.html

outline-019.html

outline-020.html

outline-021.html

outline-022.html

outline-024.html

outline-025.html

outline-026.html

outline-027.html

outline-028.html

outline-negative-offset-composited-scroll.html

outline-offset-table-001.html

outline-offset.html

outline-style-inherit.html

</wpt>

<h3 id="outline">Outlines Shorthand: the 'outline' property</h3>

<pre class="propdef shorthand">

Name: outline

Value: [ <<'outline-color'>> || <<'outline-style'>> || <<'outline-width'>> ]

Applies to: all elements

Inherited: no

Percentages: N/A

</pre>

<wpt>

crashtests/outline-scrollIntoView-crash.html

outline-001.html

outline-002.html

outline-023.html

outline-dynamic.html

outline-with-padding-001.html

parsing/outline-invalid.html

parsing/outline-shorthand.html

parsing/outline-valid.html

translucent-outline.html

</wpt>

<h3 id="outline-width">Outline Thickness: the 'outline-width' property</h3>

<div class="proposed correction" id=c2>

<span class=marker>Candidate Correction 2:</span>

[[CSS-VALUES-4]] has introduced the concept of [=snapping as a border width=]

as a type of rounding applied to some lengths

to ensure reasonable visual display.

Define 'outline-width' to use this concept,

for consistency with other border-like things.

</div>

<div class="candidate correction" id=c4>

<span class=marker>Candidate Correction 4:</span>

Remove the special-case

where 'outline-width' computes to 0

based on ''outline-style: none'',

keeping things consistent with

<span class=informative>a similar change being applied to 'column-rule-width' and 'border-width'</span>.

(See <a href="https://github.com/w3c/csswg-drafts/issues/11494">Issue 11494</a>.)

</div>

<pre class="propdef">

Name: outline-width

Value: <<line-width>>

Initial: medium

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: absolute length<ins cite=#c2 title="Candidate Correction 2">, [=snapped as a border width=]</ins><del cite=#c4 title="Candidate Correction 4">; ''0'' if the outline style is ''border-style/none''.</del>

Animation type: <del cite=#c3 title="Candidate correction 3">length</del><ins cite=#c3 title="Candidate correction 3">by computed value</ins>

</pre>

<wpt>

animation/outline-width-composition.html

animation/outline-width-interpolation.html

outline-with-001-crash.html

parsing/outline-width-computed.html

parsing/outline-width-invalid.html

parsing/outline-width-valid.html

</wpt>

<h3 id="outline-style">Outline Patterns: the 'outline-style' property</h3>

<pre class="propdef">

Name: outline-style

Value: auto | <'border-style'>

Initial: none

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: as specified

Animation type: <ins cite=#c3 title="Candidate Correction 3">discrete</ins>

</pre>

<wpt>

outline-017.html

outline-018.html

outline-auto-dynamic-change.html

outline-auto-width-001.html

outline-style-011.html

outline-style-012.html

outline-style-013.html

outline-style-014.html

parsing/outline-style-computed.html

parsing/outline-style-invalid.html

parsing/outline-style-valid.html

</wpt>

<h3 id="outline-color">Outline Colors: the 'outline-color' property</h3>

<pre class="propdef">

Name: outline-color

Value: <<color>> | invert

Initial: invert

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: The computed value for ''outline-color/invert'' is ''outline-color/invert'';

the computed value of ''outline-color/currentColor'' is ''outline-color/currentColor'' (See ''currentcolor'');

see the 'color' property for other <<color>> values.

Animation Type: <del cite=#c3 title="Candidate correction 3">color</del><ins cite=#c3 title="Candidate correction 3">by computed value</ins>

</pre>

<wpt>

animation/outline-color-interpolation.html

outline-color-001.html

parsing/outline-color-computed.html

parsing/outline-color-invalid.html

parsing/outline-color-valid.html

</wpt>

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 <a>border edge</a>,

it should follow the 'border-radius' curve.

The position of the outline may be affected by descendant boxes.

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.

The 'outline-width' property accepts the same values as 'border-width'

([[css-backgrounds-3#border-width]]).

The 'outline-style' property accepts the same values as 'border-style'

([[css-backgrounds-3#border-style]]),

except that

<css>hidden</css> is not a legal outline style.

In addition, in CSS3,

'outline-style'

accepts the value ''outline-style/auto''.

The ''outline-style/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.

As such, this specification does not define how the

'outline-color'

is incorporated or used (if at all) when rendering

''outline-style/auto'' style outlines.

User agents may treat ''outline-style/auto'' as

''outline-style/solid''.

The 'outline-color' property

accepts all colors, as well as the keyword <dfn dfn-type=value for=outline-color>invert</dfn>.

''outline-color/Invert'' is expected to perform a color inversion on the pixels on the screen.

This is a common trick to ensure the focus border is visible,

regardless of color background.

Conformant UAs may ignore the ''outline-color/invert'' value

on platforms that do not support color inversion of the pixels on the screen.

If the UA does not support the ''outline-color/invert'' value

then it must reject that value at parse-time, and

the initial value of the 'outline-color' property

is the ''outline-color/currentColor'' keyword.

The 'outline' property is a shorthand property,

and sets all three of 'outline-style',

'outline-width',

and 'outline-color'.

Note: The outline is the same on all sides.

In contrast to borders,

there are no 'outline-top' or '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.

<div class="example"><p style="display:none">Example(s):

Here's an example of drawing a thick outline around a BUTTON element:

<pre><code class="lang-css">

button { outline: thick solid }

</code></pre>

</div>

Graphical user interfaces may use outlines around elements

to tell the user which element on the page has the focus.

These outlines are 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).

<div class="example"><p style="display:none">Example(s):

For example, to draw a thick black line around an element when it has the focus,

and a thick red line when it is active,

the following rules can be used:

<pre><code class="lang-css">

:focus { outline: thick solid black }

:active { outline: thick solid red }

</code></pre>

</div>

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.

<h3 id="outline-offset">Offsetting the Outline: the 'outline-offset' property</h3>

By default, the outline is drawn starting just outside the <a>border edge</a>.

However, it is possible to offset the outline and draw it beyond the <a>border edge</a>.

<pre class="propdef">

Name: outline-offset

Value: <<length>>

Initial: 0

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: <del cite=#c3 title="Candidate Correction 3"><<length>> value in absolute units (px or physical).</del><ins cite=#c3 title="Candidate correction 3">absolute length</ins>

Animation type: <del cite=#c3 title="Candidate Correction 3">length</del><ins cite=#c3 title="Candidate correction 3">by computed value</ins>

</pre>

<wpt>

animation/outline-offset-composition.html

animation/outline-offset-interpolation.html

neg-outline-offset-border-radius-crash.html

negative-outline-offset.html

outline-offset-001.html

parsing/outline-offset-computed.html

parsing/outline-offset-invalid.html

parsing/outline-offset-valid.html

</wpt>

If the computed value of 'outline-offset'

is anything other than 0,

then the outline is outset from the <a>border edge</a> by that amount.

<div class="example"><p style="display:none">Example(s):

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:

<pre><code class="lang-css">

:focus,:active { outline-offset: 2px }

</code></pre>

</div>

<p id=negative-offset>Negative values must cause the outline

to shrink into the border box.

Both the height and the width of 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.

<h2 id="resizing-and-overflow">Resizing &amp; Overflow</h2>

CSS2.1 provides a mechanism for controlling the appearance of a scrolling mechanism

(e.g. scrollbars)

on block container elements.

This specification adds to that a mechanism for controlling

user resizability of elements as well as the ability to specify text overflow behavior.

<h3 id="resize" caniuse="css-resize">Resizing Boxes: the 'resize' property</h3>

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.

<div class="correction proposed" id=c1>

<span class="marker">Candidate Correction 1:</span>

Now that ''overflow: visible'' is no longer the only value

of the 'overflow' property which doesn't cause the element to become a [=scroll container=],

adjust what elements to which the 'resize' property applies to

to match the original intent,

rather than the literal text.

</div>

<pre class="propdef">

Name: resize

Value: none | both | horizontal | vertical

Initial: none

Applies to: elements <del cite=#c1 title="Candidate Correction 1">with 'overflow' other than visible,</del><ins cite=#c1 title="Candidate Correction 1">that are <a>scroll containers</a></ins>

and optionally replaced elements such as images, videos, and iframes

Inherited: no

Percentages: N/A

Computed value: <del cite=#c3 title="Candidate correction 3">as </del>specified<ins cite=#c3 title="Candidate correction 3"> keyword</ins>

Animation type: <ins cite=#c3 title="Candidate correction 3">discrete</ins>

</pre>

<wpt>

parsing/resize-computed.html

parsing/resize-invalid.html

parsing/resize-valid.html

resize-001.html

resize-002.html

resize-003.html

resize-004.html

resize-005.html

resize-006.html

resize-007.html

resize-008.html

resize-009.html

resize-010.html

resize-011.html

resize-012.html

resize-013.html

resize-014.html

resize-015.html

resize-016.html

resize-017.html

resize-018.html

resize-019.html

resize-020.html

resize-021.html

resize-change-margin.html

resize-child-will-change-transform.html

resize-generated-content.html

resize-interactive.html

</wpt>

<dl>

<dt>none</dt>

<dd>The UA does not present a resizing mechanism on the element,

and the user is given no direct manipulation mechanism to resize the element.</dd>

<dt>both</dt>

<dd>The UA presents a bidirectional resizing mechanism

to allow the user to adjust both the height and the width of the element.</dd>

<dt>horizontal</dt>

<dd>The UA presents a unidirectional horizontal resizing mechanism

to allow the user to adjust only the width of the element.</dd>

<dt>vertical</dt>

<dd>The UA presents a unidirectional vertical resizing mechanism

to allow the user to adjust only the height of the element.</dd>

</dl>

Currently it is possible to control the appearance of the scrolling mechanism (if any)

on an element using the 'overflow' property

(e.g. <code class="lang-css">overflow: scroll</code> vs. <code class="lang-css">overflow: hidden</code> 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.

<p>

The 'resize' property applies to elements

<del cite=#c1 title="Candidate Correction 1">

whose computed 'overflow' value

is something other than ''visible''.

</del>

<ins cite=#c1 title="Candidate Correction 1">

that are <a>scroll containers</a>.

</ins>

UAs may also apply it,

regardless of the value of the 'overflow' property,

to:

<ul>

<li>Replaced elements representing images or videos, such as <{img}>, <{video}>, <{picture}>, <{svg}>, <{object}>, or <{canvas}>.

<li>The <{iframe}> element.

</ul>

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 the {{CSSPseudoElement}} interface (See [[css-pseudo-4]]).

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 <a href="https://www.w3.org/TR/css-style-attr/#style-attribute">style attribute</a> 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 where user attempts to resize an element

appear to be overridden or ignored, e.g. because of ''!important'' cascading declarations that supersede

that element’s <a href="https://www.w3.org/TR/css-style-attr/#style-attribute">style attribute</a>

'width' and 'height' properties in the DOM.

Changes to the computed value of an element's 'resize' property

do not reset changes to the <a href="https://www.w3.org/TR/css-style-attr/#style-attribute">style attribute</a> made due to

user resizing of that element.

<div class="example"><p style="display:none">Example(s):

For example,

to make iframes scrollable <em>and</em> resizable,

the following rule can be used:

<pre><code class="lang-css">

iframe,object[type^="text/"],

object[type$="+xml"],object[type="application/xml"] {

overflow:auto;

resize:both;

}

</code></pre>

</div>

<!--

too bad we don't have @viewport yet. otherwise this would be cool:

<pre><code class="lang-css">

@viewport {

width: 100px;

height: 100px;

overflow: hidden;

resize: none

} /* display content in a non-resizable 100px by 100px window */

</code></pre>

-->

<h3 id="text-overflow" caniuse="text-overflow">

Overflow Ellipsis: the 'text-overflow' property</h3>

<pre class="propdef">

Name: text-overflow

Value: clip | ellipsis

Initial: clip

Applies to: block containers

Inherited: no

Percentages: N/A

Computed value: <del cite=#c3 title="Candidate correction 3">as </del>specified<ins cite=#c3 title="Candidate correction 3"> keyword</ins>

Animation type: <ins cite=#c3 title="Candidate correction 3">discrete</ins>

</pre>

<wpt>

crashtests/text-overflow-ellipsis-multiline-crash.html

parsing/text-overflow-computed.html

parsing/text-overflow-invalid.html

parsing/text-overflow-valid.html

text-overflow-001.html

text-overflow-002.html

text-overflow-003.html

text-overflow-004.html

text-overflow-005.html

text-overflow-006.html

text-overflow-007.html

text-overflow-008.html

text-overflow-009.html

text-overflow-010.html

text-overflow-011.html

text-overflow-012.html

text-overflow-013.html

text-overflow-014.html

text-overflow-015.html

text-overflow-016.html

text-overflow-017.html

text-overflow-020.html

text-overflow-021.html

text-overflow-022.html

text-overflow-023.html

text-overflow-024.html

text-overflow-025.html

text-overflow-026.html

text-overflow-027.html

text-overflow-028.html

text-overflow-029.html

text-overflow-030.html

text-overflow-change-color.html

text-overflow-ellipsis-abspos-in-inline-block-crash-001.html

text-overflow-ellipsis-hyphen.html

text-overflow-ellipsis-indent-001.html

text-overflow-ellipsis-multiline-001.html

text-overflow-ellipsis-self-painting.html

text-overflow-ellipsis-width-001.html

text-overflow-ruby.html

text-overflow-string-001.html

text-overflow-string-002.html

text-overflow-string-003.html

text-overflow-string-004.html

text-overflow-string-005.html

text-overflow-string-006.html

text-overflow-string-007.html

text-overflow.html

</wpt>

This property specifies rendering when inline content overflows

its <a>end</a> line box edge

in the inline progression direction of its block container element ("the block")

that has 'overflow'

other than ''visible''.

Text can overflow for example when it is prevented from wrapping

(e.g. due to <code class="lang-css">white-space: nowrap</code>

or a single word is too long to fit).

Values have the following meanings:

<dl data-dfn-for="text-overflow" class="valuedef">

<dt><dfn id=overflow-clip dfn-type=value>clip</dfn>

<dd>Clip inline content that overflows its block container element. Characters may be only partially rendered.

<dt><dfn id=overflow-ellipsis dfn-type=value>ellipsis</dfn>

<dd>

Render an ellipsis character (U+2026)

to represent clipped inline content.

Implementations may substitute a more language, script, or writing-mode appropriate

ellipsis character,

or three dots "..." if the ellipsis character is unavailable.

</dl>

The term "character" is used in this property definition

for better readability and means "grapheme cluster" [[!UAX29]]

for implementation purposes.

For the ellipsis value

implementations must hide characters and

<a href="https://www.w3.org/TR/CSS2/visuren.html#inline-boxes">

atomic inline-level elements</a>

at the <a>end</a> edge of the line as necessary to fit the ellipsis, and

place the ellipsis immediately adjacent

to the <a>end</a> edge of the remaining inline content.

<div class="candidate correction" id=c5>

<span class=marker>Candidate Correction 5:</span>

Relax the positioning requirement for the ellipsis

based on implementation experience.

<blockquote>

<ins>

In order to avoid jitter in the position of the ellipsis

as scrolling reveals more content,

user agents may adjust the position of the ellipsis

to be adjacent to the end of the line,

or may fade/hide the ellipsis during scrolling.

</ins>

</blockquote>

</div>

The first character or

<a href="https://www.w3.org/TR/CSS2/visuren.html#inline-boxes">

atomic inline-level element</a>

on a line

must be clipped rather than ellipsed.

<div class=example>

<h4 id="bidi-ellipsis" class="no-num no-toc">Bidi ellipsis examples</h4>

These examples demonstrate which characters get hidden

to make room for the ellipsis in a bidi situation:

those visually at the end edge of the line.

Sample CSS:

<pre highlight=css>

div {

font-family: monospace;

white-space: pre;

overflow: hidden;

width: 9ch;

text-overflow: ellipsis;

}

</pre>

Sample HTML fragments, renderings, and your browser:

<table class="awesome-table data">

<thead><tr><th>HTML<th>Reference rendering<th>Your Browser</thead>

<tr>

<td><code highlight=html>&lt;div>שלום 123456&lt;/div></code><td><div style="font-family:monospace">123456 ם…</div><td><div style="font-family: monospace; white-space: pre; overflow: hidden; width: 9ch; text-overflow: ellipsis">שלום 123456</div>

<tr><td><code highlight=html>&lt;div dir=rtl>שלום 123456&lt;/div></code><td><div style="font-family:monospace">…456 שלום</div><td><div style="font-family: monospace; white-space: pre; overflow: hidden; width: 9ch; text-overflow: ellipsis" dir=rtl>שלום 123456</div>

</table>

</div>

<h4 id="ellipsing-details" class="no-num no-toc">ellipsing details</h4>

<ul>

<li>

Ellipsing only affects rendering and must not affect layout

nor dispatching of pointer events:

The UA should dispatch any pointer event on the ellipsis to the elided element,

as if 'text-overflow' had been ''text-overflow/none''.

<li>

The ellipsis is styled and baseline-aligned according to

the block.

<li>