url()

The url() function lets us import an external resource for use in CSS, usually a file. It takes a URL pointing to the resource, which can be absolute (i.e., includes the domain) or relative (i.e., does not include the domain), and even a blob or data URL. It can be used as a standalone value or as a parameter on other functions, such as image(), cross-fade(), and attr().

.element {
  /* Imports an image file for use as the element's background */
  background-image: url("https://picsum.photos/id/40/800/450");
  background-size: cover;
}

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

Syntax

<url()> = url( <string> <url-modifier>* ) | <url-token>

Arguments

/* URL with quotes  */
background-image: url("https://example.com/image.jpg");
background-image: image-set(
  url("image.avif") type("image/avif"),
  url("image.webp") type("image/webp"),
  url("image.png") type("image/png") 1x
);

/* URL without quotes */
background-image: url(https://example.com/illustration.webp);

/* Local Files */
background-image: url("images/hero-banner.jpg");
background-image: url("../assets/logo.png");

/* Remotes files */
background-image: url("https://cdn.example.com/images/banner.jpg");
@import url("https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700&display=swap");

The url() function takes a URL as its only argument, which can be quoted or unquoted. As simple as this seems, it might be tricky in some cases because url() reads its contents literally. As a result, you cannot use custom variables because the browser will think the var() function is part of the URL:

.element{
  --bar: https://example.com/image.png;
  background-image: url(var(--bar)); /* ❌ */
}

url() can take a quoted string (either single or double) or a unquoted token. While a quoted URL can take any string format, an unquoted token can’t. Specifically, an unquoted token cannot contain spaces, newlines, whitespaces, or unescaped special characters. However, you can still use it with special characters, provided that you escape them first.

.element {
  background: url(my image.png); /* ❌ */
  background: url(my\ image.png); /* ✅ */
}

Basic usage

The url() function is used in different properties to import resources. For example, in…

• background-image to use an image as an element’s background.
• border-image-source to define an image for border styling.
• content to insert an image or other resource in pseudo-elements.
• cursor to specify a custom cursor image.
• list-style-image to use an image as a list item marker.
• mask-image to apply an image as a mask.
• offset-path to reference an SVG path for motion effects.

It can also be used with some at-rules such as @document, @font-face, and @import.

Hero background with url()

One of the most popular uses of the CSS url() function is with the background-image property:

.hero {
  background-image: url("https://example.com/image.jpg");
  background-size: cover;
  background-position: center;
}

Custom fonts with url()

Another popular use of the url() function is to @import custom fonts into your site. The default CSS fonts are limited, and there are thousands of beautiful fonts online that you can use.

@import url("https://example.com/myfonts.css");

body {
  font-family: "Open Sans", sans-serif;
}

If you have the link to the URL of the font’s online file, or you have it saved locally in the public folder of your repo, you can use @font-face to instantiate the font, rather than the @import at-rule:

@font-face {
  font-family: "CustomFont";
  src: url("/fonts/opensans/regular.woff2") format("woff2");
  font-weight: normal;
  font-display: swap;
}

body {
  font-family: "CustomFont", Arial, sans-serif;
  padding: 20px;
  background: #f4f4f4;
  margin: 0;
}

Inline SVG icon with url()

This is a “not-so popular” use of the url() function, but we can even use a data URL to add an inline SVG:

.icon-text:not(:first-child)::before {
  content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 24 24' fill='none' stroke='%23333' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9 18l6-6-6-6'/%3E%3C/svg%3E");
  position: absolute;
  left: 0;
  top: 50%;
  transform: translateY(-50%);
}

CSS border image with url()

Another unpopular use of the url() function is with the border-image property. The CSS border-image property, as its name implies, is used to create a border around an element, but with an image rather than conventional strokes.

.bordered-box {
  border: 10px solid;
  border-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='30' height='30' viewBox='0 0 30 30'%3E%3Crect width='30' height='30' fill='%23ddd'/%3E%3Crect x='5' y='5' width='20' height='20' fill='%23f0f0f0'/%3E%3C/svg%3E")
    10 stretch;
}

Image as a list item bullet

Rather than selecting the default list-style types, you can choose to use an image of your choice in your site by setting the list-style-image property to a url() of your choice:

ul {
  list-style-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%23333' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z'/%3E%3C/svg%3E");
  padding-left: 40px;
}

Specification

The url() function is defined in the CSS Values and Units Module Level 4 draft, which is currently in Editor’s Draft.

Browser support

The CSS url() function has baseline support across all modern browsers.

Related