Compatibility

Living Standard — Last Updated

Issue Tracking:
GitHub
Participate:
GitHub whatwg/compat (new issue, open issues)
IRC: #whatwg on Freenode
Commits:
GitHub whatwg/compat/commits
@compatstandard

Abstract

This standard describes a collection of non-standard (and often vendor-prefixed) CSS properties and DOM APIs that web browsers need to support for compatibility with the de facto web.

1. Introduction

This section is non-normative.

There exists an increasingly large corpus of web content that depends on web browsers supporting a number of webkit-prefixed CSS properties and DOM APIs for functionality or layout. This holds especially true for mobile-optimized web content.

This specification aims to describe the minimal set of webkit-prefixed CSS properties and DOM APIs that user agents are required to support for web compatibility.

The Non-Standard Compatibility wiki page will serve as a rough guide for what this specification intends to cover.

2. Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the keyword ("must", "should", "may", etc.) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

3. CSS Compatibility

3.1. CSS At-rules

The following -webkit- vendor prefixed at-rules must be supported as aliases of the corresponding unprefixed at-rules:

-webkit- prefixed at-rule alias unprefixed at-rule
@-webkit-keyframes @keyframes

3.2. CSS Media Queries

3.2.1. -webkit-device-pixel-ratio

Name: -webkit-device-pixel-ratio
For: @media
Value: <number>
Type: range

-webkit-device-pixel-ratio must be treated as an alias of the resolution range type media feature, with its value interpreted as a dppx unit.

The min- or max- prefixes on range features must not apply to -webkit-device-pixel-ratio, instead the following aliases must be used:

legacy -webkit- prefixed range media feature alias standard prefixed range media feature
-webkit-min-device-pixel-ratio min-resolution
-webkit-max-device-pixel-ratio max-resolution

3.2.2. -webkit-transform-3d

Name: -webkit-transform-3d
For: @media
Value: <mq-boolean>
Accepts min/max prefixes: no

The -webkit-transform-3d media feature is used to query whether the user agent supports CSS 3D transforms. [css-transforms-1]

If the user agent supports 3D transforms, the value will be 1. Otherwise the value is 0.

3.3. CSS Gradients

3.3.1. -webkit-linear-gradient()

-webkit-linear-gradient() must be treated as an alias of linear-gradient as defined in [css3-images-20110217].

3.3.2. -webkit-radial-gradient()

-webkit-radial-gradient() must be treated as an alias of radial-gradient as defined in [css3-images-20110217].

3.3.3. -webkit-repeating-linear-gradient()

-webkit-repeating-linear-gradient() must be treated as an alias of repeating-linear-gradient as defined in [css3-images-20110217].

3.3.4. -webkit-repeating-radial-gradient()

-webkit-repeating-radial-gradient() must be treated as an alias of repeating-radial-gradient as defined in [css3-images-20110217].

3.4. CSS Properties

3.4.1. Simple property aliases

The following -webkit- vendor prefixed properties must be supported as aliases of the corresponding unprefixed property:

-webkit- prefixed property alias unprefixed property
-webkit-align-items align-items
-webkit-align-content align-content
-webkit-align-self align-self
-webkit-animation-name animation-name
-webkit-animation-duration animation-duration
-webkit-animation-timing-function animation-timing-function
-webkit-animation-iteration-count animation-iteration-count
-webkit-animation-direction animation-direction
-webkit-animation-play-state animation-play-state
-webkit-animation-delay animation-delay
-webkit-animation-fill-mode animation-fill-mode
-webkit-animation animation
-webkit-backface-visibility backface-visibility
-webkit-background-origin background-origin
-webkit-background-size

Not simple. See issue #28.

background-size
-webkit-border-bottom-left-radius border-bottom-left-radius
-webkit-border-bottom-right-radius border-bottom-right-radius
-webkit-border-top-left-radius border-top-left-radius
-webkit-border-top-right-radius border-top-right-radius
-webkit-border-radius border-radius
-webkit-box-shadow box-shadow
-webkit-box-sizing box-sizing
-webkit-flex flex
-webkit-flex-basis flex-basis
-webkit-flex-direction flex-direction
-webkit-flex-flow flex-flow
-webkit-flex-grow flex-grow
-webkit-flex-shrink flex-shrink
-webkit-flex-wrap flex-wrap
-webkit-filter filter
-webkit-justify-content justify-content
-webkit-mask mask
-webkit-mask-box-image mask-border
-webkit-mask-box-image-outset mask-border-outset
-webkit-mask-box-image-repeat mask-border-repeat
-webkit-mask-box-image-slice mask-border-slice
-webkit-mask-box-image-source mask-border-source
-webkit-mask-box-image-width mask-border-width
-webkit-mask-clip mask-clip
-webkit-mask-composite mask-composite
-webkit-mask-image mask-image
-webkit-mask-origin mask-origin
-webkit-mask-position mask-position
-webkit-mask-repeat mask-repeat
-webkit-mask-size mask-size
-webkit-order order
-webkit-perspective perspective
-webkit-perspective-origin perspective-origin
-webkit-transform-origin transform-origin
-webkit-transform-style transform-style
-webkit-transform transform
-webkit-transition-delay transition-delay
-webkit-transition-duration transition-duration
-webkit-transition-property transition-property
-webkit-transition-timing-function transition-timing-function
-webkit-transition transition

3.4.2. Prefixed property aliases

The following -webkit- vendor prefixed properties must be supported as aliases of the corresponding unprefixed properties. If the user agent does not ship the unprefixed equivalent, the -webkit- prefixed property must be treated as an alias of the user agent’s own vendor prefixed property.

-webkit- prefixed property alias (vendor prefixed) property
-webkit-text-size-adjust (-prefix-)text-size-adjust


As soon as each property is unprefixable it can be defined as a "simple" alias.

3.4.3. Property mappings

The following -webkit- vendor prefixed properties must be supported as mappings to the corresponding unprefixed property:

-webkit- prefixed property unprefixed property
-webkit-box-flex flex-grow
-webkit-box-ordinal-group order
-webkit-box-align align-items
-webkit-box-pack justify-content

3.4.4. Keyword mappings

The following -webkit- vendor prefixed keywords must be supported as mappings to the corresponding unprefixed keyword:

-webkit- prefixed keyword unprefixed property keyword
-webkit-box flex
-webkit-flex flex
-webkit-inline-box inline-flex
-webkit-inline-flex inline-flex

3.4.5. Foreground Text Clipping: the -webkit-background-clip property

Name: -webkit-background-clip
Value: border-box | padding-box | content-box | text
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: "text"
Animatable: no

The -webkit-background-clip property—when its value is text—creates a background clipping region from the outer text stroke of the foreground text (including alpha transparency).

The -webkit-background-clip property is a simple alias of the background-clip property for all other <box> values.

Note that the root element has a different background painting area, and thus the -webkit-background-clip property has no effect when specified on it. See the backgrounds of special elements.
border-box
The background is painted within (clipped to) the border box.
padding-box
The background is painted within (clipped to) the padding box.
content-box
The background is painted within (clipped to) the content box.
text
Indicates that the background image should clip to the foreground text

Here’s an example showing how to use -webkit-background-clip: text together with -webkit-text-fill-color: transparent to achieve text with a gradient color effect.
p {
  background: linear-gradient(90deg, red, blue);
  color: #fff;
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

Browsers that don’t support -webkit-background-clip or -webkit-text-fill-color will use the color declaration as a fallback color.

3.4.6. Text Fill and Stroking

3.4.6.1. Foreground Text Color: the -webkit-text-fill-color property
Name: -webkit-text-fill-color
Value: <color>
Initial: currentcolor
Applies to: all elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: an RGBA color
Animatable: as color

The -webkit-text-fill-color property defines the foreground fill color of an element’s text content.

Here’s an example showing -webkit-text-fill-color will always determine the foreground fill color of an element’s text.
.one {
  color: blue;
  /* the following can be omitted because it’s the initial value:
  -webkit-text-fill-color: currentcolor; */
}

.two {
  color: red;
  -webkit-text-fill-color: blue;
}

Elements with the one or two classes will have blue text.

3.4.6.2. Text Stroke Color: the -webkit-text-stroke-color property
Name: -webkit-text-stroke-color
Value: <color>
Initial: currentcolor
Applies to: all elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: an RGBA color
Animatable: as color

The -webkit-text-stroke-color property specifies a stroke color for an element’s text.

3.4.6.3. Text Stroke Thickness: the -webkit-text-stroke-width property
Name: -webkit-text-stroke-width
Value: <line-width>
Initial: 0
Applies to: all elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: absolute width
Animatable: no

The -webkit-text-stroke-width property specifies the width of the stroke drawn at the edge of each glyph of an element’s text. A zero value results in no stroke being painted. A negative value is invalid.

3.4.6.4. Text Stroke Shorthand: the -webkit-text-stroke property
Name: -webkit-text-stroke
Value: <line-width> || <color>
Initial: See individual properties
Applies to: See individual properties
Inherited: yes
Percentages: N/A
Media: visual
Computed value: See individual properties
Animatable: See individual properties

The -webkit-text-stroke property is a shorthand property for setting the stroke width and stroke color of an element’s text.

Here are two examples showing how to use the longhand and shorthand -webkit-text-stroke properties to achieve white text with a black stroked text effect.
.stroked-text-longhand {
  color: #fff;
  -webkit-text-stroke-color: #000;
  -webkit-text-stroke-width: 1px;
}

.stroked-text-shorthand {
  -webkit-text-fill-color: #fff;
  -webkit-text-stroke: thin #000;
}
The element
<p class="stroked-text-longhand">Serious typography</p>
would be rendered as follows:

image of stroked text

4. DOM Compatibility

4.1. The WebKitCSSMatrix interface

WebKitCSSMatrix is now defined by the DOM Geometry specification. [geometry-1].

4.2. window.orientation API

partial interface Window {
    readonly attribute short orientation;
    attribute EventHandler onorientationchange;
};

partial interface HTMLBodyElement {
    attribute EventHandler onorientationchange;
};

When getting the orientation attribute, the user agent must run the following steps:

  1. Return the responsible document’s current window.orientation angle.

Whenever the viewport is drawn at a different angle compared to the device’s natural orientation, the user agent must run the following steps:

  1. Fire an event named orientationchange at the Window object of the active document.

User agents implementing the window.orientation attribute and its associated orientationchange event must not expose them on Desktop platforms.

iOS Safari also fires an orientationchange event on the body element, but other implementations do not, suggesting it’s not required for compatibility with the web.

4.2.1. window.orientation angle

The possible values for the window.orientation angle are: -90, 0, 90, 180. User agents must support the -90, 0 and 90 values and may optionally support 180.

0 represents the natural orientation. -90 represents a rotation 90 degrees clockwise from the natural orientation. 90 represents a rotation 90 degrees counterclockwise from the natural orientation. 180 represents a rotation 180 degrees from the natural orientation.

In order to determine the current window.orientation angle, the user agent must run the following steps:

  1. Return the result of step 3 of the ScreenOrientation's update the orientation information algorithm with the following changes:
    1. If the orientation angle is less than or equal to 180, return the orientation angle
    2. If the orientation angle is greater than 180, return the orientation angle - 360.
    3. If the resulting orientation angle is 180 and the user agent does not support that value, return 0.

4.2.2. Event Handlers on Window objects and body elements

The following are the event handlers and their corresponding event handler event types that must be supported on all Window objects and body elements as attributes:

event handler event handler event type
onorientationchange orientationchange
WebKit also has this on HTMLFrameSetElement. It’s unclear if this is needed for compatibility.

Acknowledgements

Thanks to Alan Cutter, Chris Rebert, Daniel Holbert, David Håsäther, hexalys, Jean-Yves Perrier, Jacob Rossi, Philip Jägenstedt, Simon Pieters, Stanley Stuart, William Chen and Your Name Here for feedback and contributions to this standard.

Thanks to Mounir Lamouri and Marcos Cáceres for defining the ScreenOrientation interface. [screen-orientation]

Special thanks to Apple and the WebKit.org blog authors for providing initial descriptions of much of the content defined in this specification.

This standard is written by Mike Taylor (Mozilla, miket@mozilla.com).

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS22]
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. Draft. URL: https://drafts.csswg.org/css2/
[HTML]
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[WHATWG-DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr.. CSS Box Alignment Module Level 3. 18 December 2014. WD. URL: http://dev.w3.org/csswg/css-align/
[CSS-ANIMATIONS-1]
CSS Animations Module Level 1 URL: https://drafts.csswg.org/css-animations-1/
[CSS-BACKGROUNDS-3]
CSS Backgrounds and Borders Module Level 3 URL: https://drafts.csswg.org/css-backgrounds-3/
[CSS-COLOR-3]
CSS Color Module Level 3 URL: https://drafts.csswg.org/css-color-3/
[CSS-COLOR-4]
CSS Color Module Level 4 URL: https://drafts.csswg.org/css-color-4/
[CSS-CONDITIONAL-3]
CSS Conditional Rules Module Level 3 URL: https://drafts.csswg.org/css-conditional-3/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 15 October 2015. WD. URL: http://dev.w3.org/csswg/css-display/
[CSS-FLEXBOX-1]
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Flexible Box Layout Module Level 1. 14 May 2015. LCWD. URL: http://dev.w3.org/csswg/css-flexbox/
[CSS-MASKING-1]
Dirk Schulze; Brian Birtles; Tab Atkins Jr.. CSS Masking Module Level 1. 26 August 2014. CR. URL: http://dev.w3.org/fxtf/css-masking-1/
[CSS-SIZE-ADJUST-1]
CSS Mobile Text Size Adjustment Module Level 1 URL: https://drafts.csswg.org/css-size-adjust-1/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. 26 November 2013. WD. URL: http://dev.w3.org/csswg/css-transforms/
[CSS-TRANSITIONS-1]
CSS Transitions Module Level 1 URL: https://drafts.csswg.org/css-transitions-1/
[CSS-UI-3]
Tantek Çelik; Florian Rivoal. CSS Basic User Interface Module Level 3 (CSS3 UI). 7 July 2015. CR. URL: http://dev.w3.org/csswg/css-ui/
[CSS-VALUES]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 11 June 2015. CR. URL: http://dev.w3.org/csswg/css-values/
[CSS3-IMAGES-20110217]
Elika Etemad; Tab Atkins Jr.. CSS Image Values and Replaced Content Module Level 3. 17 February 2011. WD. URL: http://www.w3.org/TR/2011/WD-css3-images-20110217/
[FILTERS-1]
Filter Effects Level 1 URL: https://drafts.fxtf.org/filters-1/
[GEOMETRY-1]
Simon Pieters; Dirk Schulze; Rik Cabanier. Geometry Interfaces Module Level 1. 25 November 2014. CR. URL: http://dev.w3.org/fxtf/geometry/
[MEDIAQUERIES-4]
Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. 5 June 2014. WD. URL: http://dev.w3.org/csswg/mediaqueries-4/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SCREEN-ORIENTATION]
Mounir Lamouri; Marcos Caceres. The Screen Orientation API. 15 December 2015. WD. URL: https://w3c.github.io/screen-orientation/

Property Index

Name Value Initial Applies to Inh. %ages Media Ani­mat­able Com­puted value
-webkit-background-clip border-box | padding-box | content-box | text none all elements no N/A visual no "text"
-webkit-text-fill-color <color> currentcolor all elements yes N/A visual as color an RGBA color
-webkit-text-stroke-color <color> currentcolor all elements yes N/A visual as color an RGBA color
-webkit-text-stroke-width <line-width> 0 all elements yes N/A visual no absolute width
-webkit-text-stroke <line-width> || <color> See individual properties See individual properties yes N/A visual See individual properties See individual properties

@media Descriptors

Name Value Initial Accepts min/max prefixes Type
-webkit-device-pixel-ratio <number> range
-webkit-transform-3d <mq-boolean> no

IDL Index

partial interface Window {
    readonly attribute short orientation;
    attribute EventHandler onorientationchange;
};

partial interface HTMLBodyElement {
    attribute EventHandler onorientationchange;
};