How can microdata include properties outside an item's HTML subtree?

Definition: In HTML microdata, itemref associates an item with additional elements identified by ID. Those elements can supply properties outside the subtree rooted at the element carrying itemscope, as long as the referenced elements are in the same tree.

Key facts

• The WHATWG HTML microdata specification defines itemref as a list of additional elements to crawl for an item's name-value pairs.
• The attribute value is an unordered set of unique, space-separated tokens. Each token is an ID of an element in the same tree.
• An element must have itemscope when it carries itemref; the specification makes this a conformance requirement.
• The property-finding algorithm adds the item's children and the elements found by its itemref IDs to a pending list.
• The WHATWG HTML DOM section on the id attribute requires an HTML ID to be unique in its element's tree, contain at least one character, and contain no ASCII whitespace.

How does itemref connect a detached element?

Put itemscope and itemref on the item root. Give each referenced element an id, then put itemprop on that element or on a descendant. The value a b below names two elements in the same tree. The first target contributes name; the second target is itself a nested item and follows another reference for its properties.

<div itemscope id="amanda" itemref="a b"></div>
<p id="a">Name: <span itemprop="name">Amanda</span></p>
<div id="b" itemprop="band" itemscope itemref="c"></div>
<div id="c">
 <p>Band: <span itemprop="name">Jazz Band</span></p>
 <p>Size: <span itemprop="size">12</span> players</p>
</div>

The specification says this arrangement gives the same result as the equivalent nested markup: the first item has name set to Amanda and band set to another item; that second item has name set to Jazz Band and size set to 12.

How does the property-finding algorithm traverse the references?

The algorithm starts with the item root in memory and its child elements in a pending list. If the root has itemref, the user agent splits its value on ASCII whitespace. For each token, it finds the first element with that ID in the root's tree and adds that element to the pending list.

The algorithm then removes pending elements one at a time. An element already in memory produces a microdata error and is skipped. For a new element without itemscope, its child elements are added to the pending list. A new element with itemprop and one or more property names is added to the results. The results are finally sorted in tree order.

This traversal means a referenced container can carry no property of its own while exposing descendant properties. An element with its own itemscope forms a separate item during traversal, so its descendants belong to that item unless another reference associates them with an outer item.

What should you check in the HTML?

First, check that every itemref token matches an id in the same tree. The DOM rules define an ID as the element's unique identifier, require uniqueness among all IDs in that tree, and prohibit ASCII whitespace in the value. IDs are opaque strings, so use the exact token written in the markup.

Next, check the item boundary. itemref is allowed on an element with itemscope, and each referenced path is processed together with the root's descendants. A duplicate token is invalid because the itemref value must contain unique tokens. A cycle in the item graph is also prohibited by the microdata specification.

Related terms

• Microdata
• How do itemscope and itemtype identify an HTML microdata item?
• How is an object nested inside another microdata item?
• Where does a microdata property's value come from in HTML?

FAQ

Can itemref point to a URL or CSS selector?

No. Its value is a set of space-separated IDs for elements in the same tree. Write the ID token itself, such as author, rather than a URL or selector expression.

Must a referenced element carry itemprop?

No. A referenced element without itemprop can act as a container whose descendants are traversed. The algorithm adds a new element's children when that element has no itemscope.

Can an element use itemref without itemscope?

No. The HTML microdata specification requires itemscope on an element that carries itemref.

Sources

1. WHATWG, "HTML Standard, Microdata", 19 October 2026
2. WHATWG, "HTML Standard, The id attribute", 19 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer