HTML Guides for foreign namespace

When the HTML parser encounters an <svg> or <math> tag, it switches from the HTML namespace into a foreign namespace (SVG or MathML, respectively). Inside these foreign contexts, only elements defined by those specifications are valid. The HTML <img> element does not exist in the SVG or MathML namespaces, so placing it there causes a parsing conflict and triggers the W3C validator error: "HTML start tag img in a foreign namespace context."

This matters for several reasons. Browsers handle this situation inconsistently — some may break out of the foreign namespace to render the <img>, while others may ignore it entirely or produce unexpected layout results. This inconsistency means your page may look correct in one browser but be broken in another. Beyond rendering issues, assistive technologies rely on proper namespace boundaries to interpret content. An <img> in the wrong namespace may lose its accessibility semantics, meaning the alt text could go unannounced to screen reader users.

How to fix it

The fix depends on which foreign namespace context contains the <img>:

Inside <svg>: Replace <img> with the SVG <image> element. Note that SVG's <image> uses the href attribute (not src) and requires x, y, width, and height attributes for positioning and sizing. Unfortunately, SVG's <image> element does not support an alt attribute directly — use a <title> child element or aria-label to provide an accessible name.

Inside <math>: Move the <img> outside the <math> element entirely, or place it inside an <mtext> element. The <mtext> element in MathML is designed to hold text content and, per the HTML parsing rules, can contain embedded HTML elements.

Examples

Incorrect: <img> inside <svg>

<svgwidth="200"height="200">

<imgsrc="diagram.png"alt="A diagram"width="200"height="200">

</svg>

Correct: using SVG <image> element

<svgwidth="200"height="200"role="img"aria-label="A diagram">

<imagehref="diagram.png"x="0"y="0"width="200"height="200"/>

</svg>

Correct: with an accessible name via <title>

<svgwidth="200"height="200"role="img"aria-labelledby="diagram-title">

<titleid="diagram-title">A diagram</title>

<imagehref="diagram.png"x="0"y="0"width="200"height="200"/>

</svg>

Incorrect: <img> inside <math>

<math>

<imgsrc="equation.png"alt="x squared plus one">

</math>

Correct: <img> inside <mtext> within <math>

<math>

<mtext>

<imgsrc="equation.png"alt="x squared plus one">

</mtext>

</math>

Correct: <img> moved outside <math>

<imgsrc="equation.png"alt="x squared plus one">

Incorrect: mixed HTML content inside <svg>

<svgwidth="300"height="150">

<rectwidth="300"height="150"fill="#eee"/>

<imgsrc="icon.png"alt="Icon"width="32"height="32">

<textx="50"y="80">Hello</text>

</svg>

Correct: using <image> alongside other SVG elements

<svgwidth="300"height="150">

<rectwidth="300"height="150"fill="#eee"/>

<imagehref="icon.png"x="10"y="10"width="32"height="32"aria-label="Icon"/>

<textx="50"y="80">Hello</text>

</svg>

If you need to place HTML content alongside or on top of an SVG, consider using the <foreignObject> SVG element, which explicitly creates an HTML namespace context within SVG:

<svgwidth="300"height="150">

<rectwidth="300"height="150"fill="#eee"/>

<foreignObjectx="10"y="10"width="100"height="100">

<imgsrc="icon.png"alt="Icon"width="32"height="32">

</foreignObject>

</svg>

The <foreignObject> approach is especially useful when you need full HTML capabilities — such as alt text on <img>, form controls, or rich text — inside an SVG graphic.

A <span> element (or any HTML element) cannot appear directly inside an SVG or MathML element without first switching back to the HTML namespace.

SVG and MathML are foreign namespaces embedded within HTML documents. When the parser encounters an <svg> or <math> element, it switches to that element's namespace. Elements placed directly inside these foreign contexts are interpreted as belonging to that namespace, not as standard HTML elements. A <span> inside <svg>, for example, is not a valid SVG element, so the validator flags it.

To include HTML content within SVG, wrap it in a <foreignObject> element. The <foreignObject> element tells the parser to switch back to the HTML namespace, allowing standard HTML elements like <span>, <div>, or <p> inside it. You must give <foreignObject> a width and height so the browser knows how much space to allocate for the HTML content.

For MathML, the equivalent approach is to use the <mtext> element (or another MathML token element) and place the HTML content inside it. The HTML parser automatically switches back to the HTML namespace when it encounters HTML elements within MathML token elements like <mtext>, <mi>, or <mo>.

Invalid example

<svgwidth="200"height="200">

<span>This text causes a validation error</span>

</svg>

Valid example using foreignObject

<svgwidth="200"height="200">

<foreignObjectx="10"y="10"width="180"height="180">

<span>This text is valid inside foreignObject</span>

</foreignObject>

</svg>

Valid example in MathML

<math>

<mtext>

<span>This text is valid inside mtext</span>

</mtext>

</math>