CSS url() Function

CSS url() Function

The CSS url() function specifies the location of a resource, such as an image, font, stylesheet, or SVG graphic.

It accepts relative URLs, absolute URLs, data URLs, and fragment references. The function is commonly used with properties such as background-image, list-style-image, and cursor, as well as the @font-face and @import at-rules.

Syntax

url("resource-address")
url('resource-address')
url(resource-address)

The url() function contains a URL identifying the resource to reference.

Examples:

background-image: url("images/background.jpg");
background-image: url('../images/background.jpg');
background-image: url("/images/background.jpg");
background-image: url("https://www.example-web.site/img/mountain-landscape.jpg");
list-style-image: url("images/bullet.svg");
cursor: url("images/cursor.cur"), pointer;

The URL can be enclosed in single quotes, double quotes, or left unquoted when its characters permit that syntax.

Using quotation marks is generally recommended for readability and to avoid problems with special characters.

The function is used within CSS declarations and at-rules that accept resource references.

Parameters

The url() function accepts a resource address.

The resource address must be suitable for the property or at-rule using it.

For example, a font file can be referenced by @font-face, but it cannot be used as a background image.

The CSS Values and Units specification also defines a syntax for URL modifiers, although no general-purpose modifiers are currently established for ordinary use.

How It Works

The url() function creates a CSS resource reference.

For example:

.box {
  background-image: url("images/background.jpg");
}

The browser resolves the URL and attempts to load the referenced image.

If the resource is available and supported, the browser uses it according to the property's rules.

The url() function does not determine how an image is sized, repeated, or positioned. Those behaviors are controlled by properties such as background-size, background-repeat, and background-position.

A URL can be syntactically valid even when the referenced file does not exist or cannot be loaded.

Loading may also be affected by network errors, browser security policies, cross-origin restrictions, or unsupported resource formats.

Relative URLs

A relative URL identifies a resource using a path relative to a base location.

In an external CSS stylesheet, relative URLs are normally resolved from the stylesheet's location, not the HTML document's location.

Consider the following project structure:

website/
  index.html
  css/
    styles.css
  images/
    background.jpg

Inside css/styles.css, the correct relative path to the image is:

.box {
  background-image: url("../images/background.jpg");
}

The ../ moves up one directory from css/ before entering images/.

Same Directory

background-image: url("background.jpg");

References a file in the same directory as the stylesheet.

Child Directory

background-image: url("images/background.jpg");

References a file in an images subdirectory of the stylesheet's directory.

Parent Directory

background-image: url("../images/background.jpg");

Moves up one directory before locating the image.

Root-Relative Paths

background-image: url("/images/background.jpg");

References the images directory at the root of the current origin.

For CSS inside an HTML <style> element, relative URLs use the document's base URL instead.

Understanding this distinction helps prevent broken image and font references when stylesheets are moved between directories.

Absolute URLs

An absolute URL includes the scheme and full resource address.

For example:

.box {
  background-image: url("https://www.example-web.site/img/mountain-landscape.jpg");
}

The browser requests the image from the specified address, regardless of where the stylesheet is located.

Absolute URLs are useful when referencing resources hosted on another domain or a content delivery network.

However, they can introduce dependencies on external servers.

If the resource becomes unavailable, is moved, or is blocked by a security policy, the browser may not display it.

Use HTTPS for externally hosted resources whenever possible.

For resources maintained within the same website, relative or root-relative paths are often easier to manage.

Quoted and Unquoted URLs

The url() function supports both quoted and unquoted URLs.

Double Quotes

background-image: url("images/background.jpg");

Single Quotes

background-image: url('images/background.jpg');

No Quotes

background-image: url(images/background.jpg);

All three declarations reference the same resource.

Unquoted URLs have additional parsing restrictions. Spaces, quotation marks, parentheses, and certain other characters must be escaped when used within an unquoted URL.

For example, a filename containing a space can be written as:

background-image: url("images/site banner.jpg");

Quotation marks make the address easier to read and avoid the need to escape the space.

For consistency, using double quotes around resource addresses is a practical convention.

Data URLs

A data URL embeds resource content directly into a CSS value rather than referencing a separate file.

For example, an SVG image can be embedded using a data URL:

.box {
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100'%3E%3Crect width='100' height='100' fill='%233498db'/%3E%3C/svg%3E");
}

This embeds a blue SVG rectangle directly in the stylesheet.

Data URLs can also contain Base64-encoded resources.

They are useful for small icons or graphics that do not need a separate network request.

However, large data URLs can increase stylesheet size and make the CSS more difficult to maintain.

Data URLs are subject to browser security restrictions and content security policies.

For larger images or frequently reused assets, separate files are usually preferable.

Fragment URLs

A fragment URL references a resource identified by an ID.

Fragments are commonly used with SVG filters, masks, gradients, and clipping paths.

For example:

.graphic {
  filter: url("#shadow-filter");
}

This references an SVG filter with the ID shadow-filter.

An external SVG resource can also contain a fragment identifier:

.graphic {
  filter: url("filters.svg#shadow-filter");
}

The browser attempts to use the identified filter from the external SVG file.

External SVG references may be subject to additional security restrictions and browser compatibility differences.

A fragment does not automatically work with every CSS property. The referenced resource must be appropriate for the property using it.

Background Images

One of the most common uses of url() is to specify an image for the background-image property.

For example:

.banner {
  background-image: url("images/banner.jpg");
  background-position: center;
  background-repeat: no-repeat;
  background-size: cover;
}

The url() function identifies the image, while the other background properties control its appearance.

A background color can provide a fallback:

.banner {
  background-color: #3498db;
  background-image: url("images/banner.jpg");
}

If the image cannot be loaded, the background color remains available.

Background images are decorative and do not provide alternative text. Images that convey essential content should generally be included using an HTML <img> element with appropriate alternative text.

Multiple Background Images

The background-image property accepts multiple image values separated by commas.

For example:

.banner {
  background-image: url("images/overlay.png"), url("images/background.jpg");
  background-position: center, center;
  background-repeat: no-repeat, no-repeat;
  background-size: cover, cover;
}

The first image is drawn above the second image.

Each image can have its own position, repetition, and size settings.

CSS gradients can also be combined with images:

.banner {
  background-image: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5)), url("images/background.jpg");
  background-position: center;
  background-size: cover;
}

The gradient appears above the background image, creating a dark overlay.

This technique is useful when text needs additional contrast over a decorative background.

Font Resources

The url() function is used in the @font-face at-rule to reference font files.

For example:

@font-face {
  font-family: "Example Font";
  src: url("../fonts/example-font.woff2") format("woff2");
  font-style: normal;
  font-weight: 400;
}
.example-text {
  font-family: "Example Font", sans-serif;
}

The src descriptor identifies the font resource.

The format() hint describes the expected font format.

The font file must exist at the specified location and be available to the browser.

When a font cannot be loaded, the browser uses another font from the font-family list.

Font files must be used in accordance with their licenses. Cross-origin font loading can also require appropriate server configuration.

Other CSS Properties

The url() function is accepted by several CSS properties and at-rules.

Importing Stylesheets

@import url("layout.css");

This imports another CSS stylesheet.

The @import rule must appear before ordinary style rules, apart from certain permitted at-rules.

Custom Cursor

.button {
  cursor: url("images/cursor.cur"), pointer;
}

The browser attempts to use the custom cursor. The pointer keyword provides a required fallback.

Generated Content

.label::before {
  content: url("images/icon.svg");
}

This inserts an image as generated content before the element's content.

Generated content should not be the only way important information is communicated.

CSS Custom Properties

CSS custom properties can store complete url() values for reuse.

For example:

:root {
  --background-image: url("../images/background.jpg");
}
.banner {
  background-image: var(--background-image);
}

The custom property contains the complete resource reference.

Another declaration can override the image:

.banner.alternate {
  --background-image: url("../images/alternate.jpg");
}

Do not place var() directly inside url() to construct a resource address.

For example, this is invalid:

.banner {
  --image-path: "images/background.jpg";
  background-image: url(var(--image-path));
}

Instead, store the complete url() function in the custom property and reference it using var().

When relative URLs are stored in custom properties, their resolution can depend on the stylesheet where the var() substitution is used.

Example

The following example demonstrates a CSS background image using an absolute URL.

HTML:

<div class="url-demo">
  <p>CSS Background Image</p>
</div>

CSS:

.url-demo {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 180px;
  padding: 20px;
  color: #fff;
  background-color: #34495e;
  background-image: linear-gradient(rgba(0, 0, 0, 0.45), rgba(0, 0, 0, 0.45)), url("https://www.example-web.site/img/mountain-landscape.jpg");
  background-position: center;
  background-repeat: no-repeat;
  background-size: cover;
}
.url-demo p {
  margin: 0;
  font-size: 1.25rem;
  font-weight: bold;
}

The url() function references the background image.

A semi-transparent gradient darkens the image so the white text remains easier to read.

If the image cannot be loaded, the background color and gradient remain visible.

Background Image Example

The following example uses a data URL to embed an SVG graphic directly in CSS.

HTML:

<div class="url-svg-demo">
  <p>Embedded SVG Background</p>
</div>

CSS:

.url-svg-demo {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 150px;
  padding: 20px;
  color: #fff;
  background-color: #3498db;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='40' height='40'%3E%3Ccircle cx='20' cy='20' r='8' fill='%23ffffff' fill-opacity='0.3'/%3E%3C/svg%3E");
  background-repeat: repeat;
}
.url-svg-demo p {
  margin: 0;
  padding: 12px 20px;
  background-color: rgba(0, 0, 0, 0.45);
}

The SVG creates a repeating pattern of translucent circles.

Because the graphic is embedded in the CSS, no separate image file is required.

The %23 sequence represents the hash character used in the SVG color value.

List Image Example

The following example uses url() to supply a custom image for list markers.

HTML:

<ul class="url-list-demo">
  <li>HTML Tutorials</li>
  <li>CSS References</li>
  <li>Live Code Examples</li>
</ul>

CSS:

.url-list-demo {
  padding-left: 35px;
  list-style-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12'%3E%3Ccircle cx='6' cy='6' r='5' fill='%2316a085'/%3E%3C/svg%3E");
}
.url-list-demo li {
  margin-bottom: 10px;
}

The list-style-image property uses an embedded SVG circle as the marker for each list item.

The marker graphic is provided through url(), while the list retains its normal HTML structure.

Common Uses

The url() function is used throughout CSS to reference resources.

• Background images: Display decorative images behind elements.
• Custom fonts: Load font files with @font-face.
• Stylesheet imports: Reference additional CSS files with @import.
• List markers: Use custom images for list bullets.
• Custom cursors: Reference cursor graphics with a fallback keyword.
• SVG effects: Reference filters, masks, and clipping paths.
• Border images: Use image resources for decorative borders.
• Generated content: Insert decorative images using pseudo-elements.
• Embedded graphics: Include small SVG resources using data URLs.

For example:

.icon {
  background-image: url("images/icon.svg");
  background-repeat: no-repeat;
  background-position: center;
  background-size: contain;
}

This references an SVG image and displays it as a centered, non-repeating background.

Use resource paths that are appropriate for the stylesheet's location and the website's directory structure.

Limitations

The url() function has several requirements and behaviors to consider.

• The resource address must use valid CSS URL syntax.
• Relative paths in external stylesheets are normally resolved from the stylesheet's location.
• Unquoted URLs have restrictions on spaces, quotation marks, parentheses, and other characters.
• A syntactically valid URL does not guarantee that the resource exists or can be loaded.
• Cross-origin restrictions and content security policies may prevent some resources from loading.
• The referenced resource must be appropriate for the CSS property or at-rule.
• External resources can introduce additional network requests and loading delays.
• Large data URLs can increase stylesheet size.
• Fragment references must identify compatible resources.
• The url() function cannot directly construct a URL using var() inside its parentheses.
• CSS background images do not provide HTML alternative text.

Valid URL Examples

url("images/background.jpg")
url('images/background.jpg')
url(images/background.jpg)
url("../images/background.jpg")
url("/images/background.jpg")
url("https://www.example-web.site/img/mountain-landscape.jpg")
url("data:image/svg+xml,%3Csvg%3E%3C/svg%3E")
url("#svg-filter")

Invalid URL Examples

url(images/site banner.jpg)
url("images/background.jpg"
url(var(--image-path))

The first example contains an unescaped space in an unquoted URL.

The second example is missing its closing parenthesis.

The third example attempts to substitute a custom property directly inside url(), which is not supported by its URL-token parsing rules.

Empty URLs

An empty url() value, such as url(""), is treated as an invalid resource reference rather than a request to load the current document.

Use none when a property supports it and no resource should be applied.

Security and Accessibility

Use trusted resource locations and follow applicable content security policies.

When an image communicates meaningful content, use appropriate HTML markup rather than relying only on a CSS background image.

Provide fallback colors, fonts, or cursor keywords where appropriate.

Browser Support

The CSS url() function is Baseline Widely available and is supported by Chrome, Edge, Firefox, Safari, and other major browsers.

Basic URL references have been supported since the early versions of CSS. Some newer resource types and advanced features may have different browser compatibility requirements.

For current compatibility information, visit Can I Use? and search for CSS URL functions or the specific property using the resource.

Specifications

The url() function is defined in the CSS Values and Units Module Level 4 specification.

The specification defines URL values, quoted and unquoted syntax, relative URL resolution, and related parsing requirements.

Related features include the <url> data type, background-image, list-style-image, @font-face, @import, and CSS custom properties.