Background-image - Property CSS

background-image

Summary of characteristics of the `background-image` property

Quick description

Defines the background image or gradient (multiple images or gradients can coexist).

Status

Standard

Usable for

HTML

Predefined values

none

Percentages

Not applicable.

Initial value

none

Inherited by default

No.

Animation type

Discrète : during an animation, the background-image property passes from one value to another without transition.

W3C Module

CSS Backgrounds and Borders Module

References (W3C)

🡇

🡅

CSS Backgrounds and Borders Module Level 3

Document status: CR (Candidate Recommendation)

Cascading Style Sheets Level 2 - Revision 1 Specification

Document status: REC (Recommendation)

Cascading Style Sheets specification - Version 1

Document status: DEPR (Old specification, declared obsolete or superseded)

Syntax diagram of `background-image`.

Syntax diagram of the background-image property
Click on the diagram for a detailed presentation of the values

image is an image, defined by one of the following CSS functions: url(), image(), image-set(), cross-fade(), stripes(), element().
gradient is a color gradient, defined by one of the gradient functions: conic-gradient(), linear-gradient(), radial-gradient(), repeating-conic-gradient(), repeating-linear-gradient(), repeating-radial-gradient().

Description of the `background-image` property.

background-image defines the image or images to display in the background of the element. If more than one image is shown, the first one is the one above.

If a background color is also set with the background-color property, it will be at the back of the image. The background color is therefore obscured by the image, except in the transparent parts of the image or around it. It is advisable to always set a color in addition to the background image. Indeed, if the latter is not found or is not legible, the background will at least be materialized by color.

background-image also allows you to define a color gradient to be displayed in the background of an element.

See background for a general overview of backgrounds.

Values for `background-image`.

background-image: none;

Default: No background image.

No background images are defined.
background-image: url('chemin/fichier.png'); background-image: src('chemin/fichier.png'); ⚠

Designate an image for the background. If the url is given in relative, it will be in relation to the style sheet.
Refer to url() for more details on the feature.

The src() function requires that the address of the image be written in quotation marks or in single quotes. It is then possible to use other functions as a parameter. The src() function is not yet recognized by browsers.

A background composed of an image (in this case a small circle) repeated over the entire surface of the element.
background-image: linear-gradient(0, blue, black);

Setting a color ramp for the background. The gradient can be linear, radial, or conical. Refer to the corresponding functions: linear-gradient(), radial-gradient() and conic-gradient() . Or, for repeated gradients: repeating-linear-gradient() , repeating-radial-gradient() , and repeating-conic-gradient() .

A background consisting of a linear color gradient.

A background consisting of a repeating linear gradient.
background-image: url('fichier1.png'), url('fichier2.png'), ...;

A succession of images or gradients, separated by commas, can be defined to create several backgrounds that will overlap, the first background mentioned is above.

For more information about multiple backgrounds, see background multiple.

A background consisting of a gradient from blue to transparent, and an image. The gradient is mentioned first, so it is above. The image is only visible in its transparent part.

A background consisting of an image and the same gradient that goes from blue to transparent. The image is cited first, it is above the gradient.

Note: The above examples do not mix the different images or gradients used for the background: the first background cited mask the following, except in its transparent parts. But it is possible to mix the different backgrounds. Refer to the background-blend-mode property for more details on blending backgrounds.
background-image: image(rtl 'fichier'); ⚠ background-image: image-set('fichier1' r1, 'fichier2' r2,...); ⚠

All these syntaxes are for the moment experimental. Few browsers process them, or with the specific prefix for each browser.

The image() function is equivalent to the url() function but with additional possibilities such as power to specify the direction in which the image is read (ltr or rtl).

The image-set() function accepts multiple images to give the browser a choice, depending on the resolution or aspect ratio of the image.

A background that uses the image() function.

A background that uses the image-set() function.
background-image: element(#id); ⚠

The element() function is currently experimental. Only Firefox processes it (2025), and then with the -moz- prefix.

With the element() function it is possible to retrieve the image of the element whose id is specified;

Image used by element()

The element() function retrieves the image of the element whose id is specified.

Global values
(common to all properties):


background-image: initial  (none)
background-image: inherit
background-image: revert
background-image: revertLayer
background-image: unset

See the following pages for more details: initial, inherit, revert, revert-layer, unset.

Animation of the `background-image` property.

The background-image property can be animated, but in a discontinuous way (abrupt transition from one value to another). However, some browser based on the WebKit engine animates the transition from one image to another, especially when they are not the same size.

Manipulating the `background-image` property programmatically.

Setting a background image in Javascript.

Javascript accepts a syntax with the typical CSS kebab-case notation (a hyphen to separate words), and another syntax with the camel-case notation more common in Javascript (a capital letter to separate words).


	let el = document.getElementById('id');
	el.style['background-image'] = "url('img/background-image-2.png')";
	// or
	let el = document.getElementById('id');
	el.style.backgroundImage = "url('img/background-image-2.png')";

Read in Javascript the value of `background-image`.

The following code retrieves the value of the property if it was assigned directly to the element itself via its style attribute and not by going through a CSS selector.


	let el = document.getElementById('id');
	let value = el.style['background-image'];
	// or
	let el = document.getElementById('id');
	let value = el.style.backgroundImage;

Read the computed value of `background-image` in Javascript.

The computed value is the value that results from the cascade of inheritances, or, if there is no assigned value or inherited value, the calculated value will be the initial value of the property (none in the case of background-image).

Note: If the background image was set with an image's URL, the value returned will be the absolute address of that image.


	let el = document.getElementById('id');
	let value = window.getComputedStyle(el).getPropertyValue('background-image');

Change the background image with JQuery.


 $('#id').css('background-image', "url('img/background-image-2.png')");
 // or
 $('#id').css('backgroundImage', "url('img/background-image-2.png')");

Read the computed value of the `background-image` property with JQuery.

Reading the computed value of background-image can be done with the following code.


	let value = $('#id').css('background-image');

Other codes.

More examples of Javascript and JQuery code are given on the Javascript and CSS page.

Test it yourself.

The buttons below display the value entered in the background-image property for the first button, and the calculated value for the second button. This second option allows you to see how the value of background-image is stored (serialized). In particular, we note that it is only absolute urls that are memorized.

Browsers compatibility.

No compatibility issues: all browsers correctly support the background-image property, except for SVG images that Safari processes incompletely, and for the element() function.

Column 1

Support for the background-image property to set the background image(s).

Column 2

Support gradients as a background image.

Column 3

Support for the ability to use an SVG image as a background image.

Column 4

Support for the element() function used with background-image.

Notes:

(1) Firefox takes into account the browser.display.use_document_colors user preference in about:config.

(2) SVG support in background images is incomplete.

(3) With the préfix -moz-.

background-image
property

Gradient

SVG

element()
function

Estimated overall support.

96%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

KaiOS Browser

Opéra Mobile

Chrome

Edge

Opéra

Safari

Safari sur IOS

Androïd Brower

Chrome pour Androïd

Firefox pour Androïd

Samsung Internet

Firefox

Baidu Browser

QQ Browser

UC Browser pour Androïd

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Historic of the `background-image` property.

Cascading Style Sheets specification - Version 1

First definition of background-image in the CSS Level 1 language specification.

November 17, 1995
Working Draft.
November 12, 1996
Proposed for recommendation.
December 17, 1996
Recommendation .
September 13, 2018
Old specification, declared obsolete.
Cascading Style Sheets Level 2 - Revision 1 Specification

The background-image property also accepts the inherit value.

November 04, 1997
Working Draft.
March 24, 1998
Proposed for recommendation.
May 11, 1998
Recommendation .
CSS Backgrounds and Borders Module Level 3

Ability to use a gradient instead of an image.

August 02, 2002
Working Draft.
December 17, 2009
Candidate Recommendation.