CSS Reference ยท Functions
The url() function
Reference for the CSS url() function: quoting, relative paths, data URIs, SVG fragments, where it is allowed, and CORS and performance notes, with a live example.
The url() function points to a resource: an image, a font file, an SVG fragment or another stylesheet. It is accepted by properties such as background-image, list-style-image, border-image-source, mask-image, content, cursor and by @font-face src and @import.
CSS
.hero { background-image: url("/samples/sunset.svg"); }
Try it
Syntax
CSS
url( <string> <modifier>* ) url( <unquoted-url> ) background-image: url("images/pic.png"); background-image: url(images/pic.png);
Syntax and arguments
| Part | Description |
|---|---|
| Quoted string | The recommended form. Can contain spaces, parentheses and other special characters. |
| Unquoted URL | Allowed if the address has no spaces, quotes or unescaped parentheses. |
| Relative paths | Resolved against the stylesheet's address, not the HTML page, for external stylesheets. In a <style> element or inline style they resolve against the document. |
data: URL |
Embeds the resource in the CSS. Percent-encode #, <, > and quotes in SVG. |
| Fragment | url(sprite.svg#icon) or url(#clip) references an element inside an SVG, e.g. for clip-path or filter. |
| Modifiers | Newer syntax allows request modifiers such as cross-origin(...); support is limited, so skip unless you have checked a compatibility table. |
Usage notes
- Missing files fail silently: the property is still valid, it just paints nothing. Check the network panel for 404s.
- Always add a fallback color next to a background image so text stays readable while it loads or if it fails.
- Do not embed large images as
data:URLs. They bloat the stylesheet and cannot be cached on their own. Small SVGs and tiny icons are fine. - Quote your URLs to avoid parsing surprises with spaces or parentheses.
- Cross-origin: images and backgrounds load from other sites without CORS, but fonts, masks and some SVG references need CORS headers, and the fetch is blocked without them.
- Not for text content:
url()loads resources; it cannot insert page markup or text. image-set()offers several resolutions of the same image; each item usesurl().- Performance: background images start loading only when an element uses them, which can delay above-the-fold visuals; use
<img>withfetchpriorityfor important images. - Accessibility: CSS images have no alternative text. Use
<img alt>for meaningful images.
Browser support
Supported in every browser. Request modifiers are newer and have limited support.