PLOTCASTER Photo to line art

SVG xmlns: what it is and when it is needed

What the xmlns attribute on an SVG does, when it is needed (a file, an img tag, a CSS background, a data URI) and when it is not (inline in HTML).

Published

Check a file for a missing xmlns in the viewer →

xmlns="http://www.w3.org/2000/svg" on the opening <svg> tag tells the program reading the file that its elements are SVG. An SVG file on its own needs it: without it a browser treats the file as XML of an unknown kind and draws no picture. SVG code typed straight into an HTML page does not need it, because the HTML parser already knows what <svg> means. That difference is why code that works in a page often fails once it is saved as a file.

When it is needed

Where the SVG isIs xmlns needed?
A .svg file opened in a browser or another programYes
A .svg file shown with <img>, <object>, <embed> or <iframe>Yes
A .svg file used as a CSS background-image or mask-imageYes
A data URI holding an SVGYes
A file uploaded to a cutting program or a websiteYes, to be safe: programs differ in how strict they are
<svg> written in the HTML of a pageNo
<svg> added to a page with innerHTMLNo
<svg> in JSX, as used by ReactNo
Text given to DOMParser as image/svg+xmlYes

The rule behind the table: wherever the code is read as XML, the attribute is needed. Wherever it is read as HTML, it is not. Including it in HTML does no harm, so code meant for both uses can keep it.

This is a complete file:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill="teal"/>
</svg>

And this is the same drawing for pasting into the body of an HTML page, where the attribute can be left out:

<svg viewBox="0 0 100 100" width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="teal"/>
</svg>

What it means

XML is a general way of writing data with tags, and many formats are built on it. Each format has a namespace, a unique name that says which format a tag belongs to. The name for SVG is http://www.w3.org/2000/svg. An xmlns attribute with no prefix sets the namespace for the element it is on and everything inside it, so it is written once, on the outer <svg>.

A file without it is still well-formed XML. It is just not SVG: its <circle> is a tag called circle that belongs to nothing, and a browser has no reason to draw it.

The value looks like a web address, but nothing is fetched from it. It is only a string that programs compare, letter for letter, with the one they know. Two things follow.

  • It must be exact. https://www.w3.org/2000/svg, with an s, is a different string and does not work. Neither does a trailing slash, a different year or a capital letter.
  • It is harmless. The file works with no connection to the internet, and the http is not an insecure request. A tool that rewrites every http address to https breaks each SVG file it changes.

What happens without it

  • Opened directly in a browser: the code is shown as a tree of text, or a message says the document has no style information.
  • In an <img> tag: a broken image.
  • As a CSS background: nothing is drawn.
  • In other software: it varies. Some programs accept the file anyway and others report that it is not a valid SVG.

The usual way to end up with such a file is to copy <svg> code out of a web page and save it. How to download an SVG from a website covers doing that properly.

The SVG viewer checks for this. Open a file or paste code that lacks the attribute and it adds it before drawing, says so in a warning, and Save as .svg writes a file that has it.

Older SVG files point to other things with xlink:href, as in <use xlink:href="#leaf"/>. The xlink: prefix has to be declared as well, on the same opening tag:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 100 100">
  <defs>
    <circle id="dot" r="10" fill="teal"/>
  </defs>
  <use xlink:href="#dot" x="30" y="50"/>
  <use xlink:href="#dot" x="70" y="50"/>
</svg>

This complete file draws two teal dots side by side. If xmlns:xlink is missing while an attribute still uses the prefix, the file is broken XML and fails altogether, with an error about an unbound prefix.

Current browsers also accept a plain href with no prefix, which needs no extra declaration. Some older programs read only xlink:href, so files meant for cutting or print software are often written with it.

Namespaces added by editors

A file saved by a drawing program can carry several more declarations, such as xmlns:inkscape, xmlns:sodipodi or xmlns:dc. They belong to data the editor keeps for its own use, such as guides, layer names and document details. They do no harm. Do not delete one by hand while elements or attributes with its prefix remain in the file, because that makes the same unbound prefix error. The SVG optimizer removes the editor data and then the declarations that nothing uses any more.

In JavaScript

The attribute matters only when text is being parsed. Elements made by script get their namespace from the method that creates them, not from an attribute:

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
const circle = document.createElementNS(svgNS, 'circle');

document.createElement('svg') makes an HTML element that happens to be called svg, and it is never drawn. Setting an xmlns attribute on it afterwards changes nothing.

DOMParser follows the rule in the table. With 'text/html' the attribute is not needed. With 'image/svg+xml' the text is read as XML, and without the attribute the elements that come back are not SVG elements.

In JSX, xmlns can be written as it is, though it is not needed for SVG drawn inline. Names with a colon are not allowed, so xmlns:xlink and xlink:href are written xmlnsXlink and xlinkHref.

In a data URI

An SVG inside a data URI is read as a file, so it needs the attribute:

.dot {
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 10 10'%3E%3Ccircle cx='5' cy='5' r='4'/%3E%3C/svg%3E");
}

Leaving it out is a common reason for a data URI background that shows nothing. SVG to Base64 adds a missing xmlns to what it encodes and says that it has.

Common problems

What you seeCauseFix
The file shows as code in the browserNo xmlnsAdd it to the opening <svg> tag
Works inline, broken as an image or backgroundThe sameThe same
Still broken with the attribute presentThe value is misspelt, or uses httpsUse exactly http://www.w3.org/2000/svg
Error naming an unbound or undeclared prefixA prefix such as xlink: or inkscape: is used but not declaredAdd the matching xmlns: declaration, or remove the attributes that use the prefix
Shapes made by script do not appearMade with createElementUse createElementNS

Questions

Does an SVG file need a DOCTYPE or an <?xml?> line? No. Browsers draw a file that starts directly with <svg xmlns="http://www.w3.org/2000/svg">. Editors often write both lines, and they are harmless.

Is the version attribute needed? No. Browsers ignore version="1.1".

Why does my SVG still not show? A missing namespace is one cause among several. SVG not showing goes through the others.