url() and src(), CSS functions.

url()

src()

Summary of characteristics of the `url()` function

Quick description

Specifies the address of a resource such as an image for example.

Status

Standard

Percentages

Not applicable.

Animation type

Discrète: during an animation, the url() property passes from one value to another without transition.

W3C Module

CSS Values and Units Module

References (W3C)

🡇

🡅

CSS Values and Units Module Level 5

Document status: WD (Working Draft)

CSS Values and Units Module Level 4

Document status: WD (Working Draft)

CSS Values and Units Module Level 3

Document status: CR (Candidate Recommendation)

Description of the functions `url()` and `src()`.

The function url() allows you to specify the address of an external resource, such as an image, a sound, a font, etc. The address can be indicated in quotes, in apostrophes, or without anything at all.

Example. The three syntaxes below are equivalent:


	background-image:url("path/bg-image.jpg");
	background-image:url('path/bg-image.jpg');
	background-image:url(path/bg-image.jpg);

The function src() has exactly the same role, but the address of the resource must be included in quotes or apostrophes. This allows the use of functions instead of the address. However, the function src() is still poorly recognized by current browsers (2024).


	--bkg:'path/bkg-image.jpg';
	
	/* Does not work with url(): */
	background-image:url(var(--bkg));
	
	/* Work with src(): */
	background-image:src(var(--bkg));

Fragments of image.

When the file designated by url() is an image, the syntax allows for retrieving only a portion of that image. Note! Few browsers support the feature to handle an image fragment.

The `url()` value can be used with the following properties:

@font-face : Defines all settings for a downloadable font.
@import : Importing a stylesheet, with the possibility of choosing a cascade layer.
background-image : Defines the background image or gradient (multiple images or gradients can coexist).
border-image-source : Sets the path and file name for the image used to build the border.
content : Add content to the document, mainly with the ::before and ::after selectors.
cursor : Sets the shape of the mouse cursor.
list-style-image : Defines a custom image to be used in place of bullets, in the context of a list enumeration.
mask-image : Specifies the image or SVG file that will be used as a mask.
src : Defines the source of a font file to download, or an image to display.

Syntax of the functions `url()` and `src()`.

<property>: url('path/file.ext'); <property>: src('path/file.ext'); ⚠ u

The u is the address of an external resource. With the url() function, if this resource contains spaces, parentheses, quotes, or apostrophes, it will be necessary to escape these characters with a backslash () or to enclose the address in apostrophes or quotes.

Examples :

`url(img/logo.png)`	No prohibited characters in the address.
`url(img/small logo.png)`	Space character forbidden.
`url(img/small\ logo.png)`	Escape space with backslash `\`.
`url('img/small logo.png')`	Address enclosed with apostrophes.
`url("img/small logo.png")`	Address enclosed with double quotes.

Due to the fact that the delimiter characters (quotes or apostrophes) are not mandatory, it is not possible to use the calc() or var() functions with the function url().

The function src() requires that the address u be enclosed in quotes or apostrophes. This allows for a calculation expression to be specified instead of the address.

`src(img/logo.png)`	Invalid.
`src("img/logo.png")`	Correct.
`src('img/logo.png')`	Correct.
`src(var(--adr))`	Correct.

The address u can be relative or absolute:

`url(img/logo.png)`	A relative address, evaluated in relation to the location of the stylesheet ⁽¹⁾.
`url(http://domain/img/logo.png)`	An absolute address that can refer to a resource possibly available on another domain.
`url(/img/logo.png)`	An absolute address relative to the root of the current site.

(1) If the style is directly included in the document (HTML), it is the address of this document that serves as the basis for determining the absolute address.

<property>: url('path/file.png#xywh=100,100,300,200'); ⚠ x y l h

When the function url() is used to refer to an image, it is possible to retrieve only a part of that image.

The xywh parameter (short for x, y, width, height) is treated as a bookmark indicating a portion of the image. Four numbers must be specified, separated by commas. These numbers correspond by default to pixels.

Beware of the absence of units, and the unusual equal sign in CSS.
1. x and y are the coordinates of the point at the top left of the area to be processed.
2. w and h are respectively the width and height of the area to be processed.
<property>: url('path/file.ext' m); ⚠

The parameter m is presented as a 'url-modifier' but interestingly no more precise definition exists in the standard.

If a url-modifier parameter is specified, the address must be enclosed in quotes or apostrophes.

Examples of use of the function `url()`.

Relative address.

The background image is saved on the same site. The relative address is resolved in relation to the location of the file where the style is defined. Here it concerns the current HTML page, but in most cases, it will be a separate style sheet.

Absolute address to another domain.

In this example, the background image can be saved on another site (here the W3C site).

Absolute address on the same domain.

You just need to start the address with the slash character (/) which indicates the root of the site. Here url() is used to specify the border image.

Browsers compatibility with `url()` function.

The function url() is very well recognized by all browsers. It can be used in many scenarios: defining a cursor, a bullet point, a font, etc. Refer to the corresponding property to see if a feature is supported. The table below only includes the two syntax that have been long-standing compatibility issues.

On the other hand, the function src() is very poorly supported even by browsers, even modern ones (2024).

Column 1

Support by browsers for the url() function which provides access to an external resource (image, sound, font, etc.).

Column 2

Support by browsers for the url() function in the context of the cursor property, to specify an image to be used as a cursor.

Column 3

Support by browsers of the src() function equivalent to url(), with a more rigorous syntax.

url() function
with content

url() function
with cursor

src()
function

Estimated overall support.

96%

95%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

Baidu Browser

QQ Browser

Opéra Mobile

Firefox

Chrome

Safari

Edge

Opéra

Chrome pour Androïd

Safari sur IOS

Samsung Internet

UC Browser pour Androïd

Androïd Brower

Firefox pour Androïd

KaiOS Browser

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Historic of the `url()` function.

Cascading Style Sheets specification - Version 1

The url() function has existed since the very first version of the CSS language. It is used to indicate any external resource: image, font, file to import, etc.

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

No change to the url() function.

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

No change relating to the url() function.

July 13, 2001
Working Draft.
August 28, 2012
Candidate Recommendation.
CSS Values and Units Module Level 4

Introduction of the src() function, synonymous with url() but with more rigorous syntax (obligation to specify the address between apostrophes or quotation marks).

August 14, 2018
Working Draft.
CSS Values and Units Module Level 5

No change to url() and src() functions.

September 03, 2024
Working Draft.