CSS Backgrounds and Borders Module Level 3

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-backgrounds” in the title, like this: “[css-backgrounds] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 18 August 2025 W3C Process Document.

The following features are at-risk, and may be dropped during the CR period:

animatability of box-shadow
applicability of border and its longhands to ruby base containers and ruby annotation containers

“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 subsection is not normative.

When elements are rendered according to the CSS box model [CSS-BOX-3], each element is either not displayed at all, or formatted as one or more rectangular boxes. Each box has a rectangular content area, a band of padding around the content, a border around the padding, and a margin outside the border. (The margin may actually be negative, but margins have no influence on the background and border.)

Diagram of a typical box, showing the content, padding, border and margin areas — The various areas and edges of a typical box. (This diagram is explained in the CSS Box Model Module [CSS-BOX-3].)

The properties of this module deal with the decoration of the border area and with the background of the content, padding, and border areas. Additionally the box may be given a “drop-shadow” effect with the box-shadow property.

If an element is broken into multiple box fragments, box-decoration-break [CSS-BREAK-3] defines how the borders and background are divided over the various fragments. (An element can result in more than one fragment if it is broken at the end of a line, at the end of a column or at the end of a page; and continued in the next line, column or page.)

The relative stacking order of backgrounds, borders, and shadows is given in this module. For how these layers interact with other rendered content, see Appendix E “Elaborate description of Stacking Contexts” in [CSS2].

1.1. Module Interactions

This module replaces and extends the background and border features defined in [CSS2] sections 8.5 and 14.2.

All properties in this module apply to the ::first-letter pseudo-element. The background properties and border-radius properties also apply to the ::first-line pseudo-element. The UA may (but is not required to) apply the border-image or box-shadow properties to ::first-line. The UA must not apply the border-color/style/width properties to ::first-line. [CSS2]

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types. For example, combining with CSS Images allows for using CSS gradients as background-image or border-image values. [CSS-IMAGES-3]

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.

2. Backgrounds

Each box has a background layer that may be fully transparent (the default), or filled with a color and/or one or more images. The background properties specify what color (