itemref - Reference External Properties

The `itemref` Attribute

Global Attribute HTML5

The itemref attribute allows you to reference Microdata properties that are not contained within an element with the itemscope attribute. This is useful when properties of an item are scattered across different parts of your HTML document rather than being nested together.

Quick Example

<div itemscope itemtype="http://schema.org/Person" itemref="author-bio">
<h1 itemprop="name">Jane Smith</h1>
<p itemprop="jobTitle">Software Engineer</p>
</div>

<div id="author-bio">
<p itemprop="description">
  Jane has over 10 years of experience building web applications
  and specializes in modern JavaScript frameworks.
</p>
<a itemprop="url" href="https://janesmith.dev">Visit Website</a>
</div>

<style>
[itemscope] {
  border: 2px solid #3b82f6;
  padding: 16px;
  border-radius: 8px;
  background: #eff6ff;
}
#author-bio {
  margin-top: 16px;
  border: 2px dashed #10b981;
  padding: 16px;
  border-radius: 8px;
  background: #f0fdf4;
}
</style>

Result

Interactive code playground requires JavaScript. Here's the code:

<div itemscope itemtype="http://schema.org/Person" itemref="author-bio">
<h1 itemprop="name">Jane Smith</h1>
<p itemprop="jobTitle">Software Engineer</p>
</div>

<div id="author-bio">
<p itemprop="description">
  Jane has over 10 years of experience building web applications
  and specializes in modern JavaScript frameworks.
</p>
<a itemprop="url" href="https://janesmith.dev">Visit Website</a>
</div>

<style>
[itemscope] {
  border: 2px solid #3b82f6;
  padding: 16px;
  border-radius: 8px;
  background: #eff6ff;
}
#author-bio {
  margin-top: 16px;
  border: 2px dashed #10b981;
  padding: 16px;
  border-radius: 8px;
  background: #f0fdf4;
}
</style>

Syntax

<element itemscope itemref="id-reference">Content</element>
<element itemscope itemref="id1 id2 id3">Content</element>

Values

Value	Description
`id-reference`	A space-separated list of element IDs that contain additional `itemprop` properties for this item.

Why Use `itemref`?

The itemref attribute is valuable when:

Properties are scattered across the DOM: Your page structure requires item properties to be in different locations for layout or design reasons.

Shared metadata exists: Multiple items share common properties that are defined once in the document.

Separation of concerns is needed: Content is organized semantically in your HTML, but needs to be grouped differently for structured data purposes.

Common Use Cases

Author Information in a Separate Section

<article itemscope itemtype="http://schema.org/BlogPosting"
       itemref="author-details">
<h2 itemprop="headline">Understanding Web Components</h2>
<time itemprop="datePublished" datetime="2025-03-15">
  March 15, 2025
</time>
<div itemprop="articleBody">
  <p>Web Components are a suite of different technologies...</p>
</div>
</article>

<aside id="author-details">
<h3>About the Author</h3>
<div itemprop="author" itemscope itemtype="http://schema.org/Person">
  <img itemprop="image" src="https://via.placeholder.com/80"
       alt="Author photo">
  <strong itemprop="name">John Doe</strong>
  <p itemprop="description">Technical writer and developer</p>
</div>
</aside>

<style>
article {
  border: 2px solid #6366f1;
  padding: 20px;
  border-radius: 8px;
  background: #eef2ff;
  margin-bottom: 16px;
}
aside {
  border: 2px dashed #8b5cf6;
  padding: 20px;
  border-radius: 8px;
  background: #faf5ff;
}
img {
  border-radius: 50%;
  margin-right: 12px;
  vertical-align: middle;
}
</style>

Result

Interactive code playground requires JavaScript. Here's the code:

<article itemscope itemtype="http://schema.org/BlogPosting"
       itemref="author-details">
<h2 itemprop="headline">Understanding Web Components</h2>
<time itemprop="datePublished" datetime="2025-03-15">
  March 15, 2025
</time>
<div itemprop="articleBody">
  <p>Web Components are a suite of different technologies...</p>
</div>
</article>

<aside id="author-details">
<h3>About the Author</h3>
<div itemprop="author" itemscope itemtype="http://schema.org/Person">
  <img itemprop="image" src="https://via.placeholder.com/80"
       alt="Author photo">
  <strong itemprop="name">John Doe</strong>
  <p itemprop="description">Technical writer and developer</p>
</div>
</aside>

<style>
article {
  border: 2px solid #6366f1;
  padding: 20px;
  border-radius: 8px;
  background: #eef2ff;
  margin-bottom: 16px;
}
aside {
  border: 2px dashed #8b5cf6;
  padding: 20px;
  border-radius: 8px;
  background: #faf5ff;
}
img {
  border-radius: 50%;
  margin-right: 12px;
  vertical-align: middle;
}
</style>

Shared Metadata Across Multiple Items

<div id="publisher-info">
<div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
  <meta itemprop="name" content="Tech Blog Network">
  <meta itemprop="url" content="https://techblog.example">
</div>
</div>

<article itemscope itemtype="http://schema.org/Article"
       itemref="publisher-info">
<h3 itemprop="headline">First Article</h3>
<p itemprop="abstract">Summary of the first article...</p>
</article>

<article itemscope itemtype="http://schema.org/Article"
       itemref="publisher-info">
<h3 itemprop="headline">Second Article</h3>
<p itemprop="abstract">Summary of the second article...</p>
</article>

<style>
article {
  border: 2px solid #14b8a6;
  padding: 16px;
  margin: 12px 0;
  border-radius: 6px;
  background: #f0fdfa;
}
h3 {
  margin-top: 0;
  color: #0f766e;
}
</style>

Result

Interactive code playground requires JavaScript. Here's the code:

<div id="publisher-info">
<div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
  <meta itemprop="name" content="Tech Blog Network">
  <meta itemprop="url" content="https://techblog.example">
</div>
</div>

<article itemscope itemtype="http://schema.org/Article"
       itemref="publisher-info">
<h3 itemprop="headline">First Article</h3>
<p itemprop="abstract">Summary of the first article...</p>
</article>

<article itemscope itemtype="http://schema.org/Article"
       itemref="publisher-info">
<h3 itemprop="headline">Second Article</h3>
<p itemprop="abstract">Summary of the second article...</p>
</article>

<style>
article {
  border: 2px solid #14b8a6;
  padding: 16px;
  margin: 12px 0;
  border-radius: 6px;
  background: #f0fdfa;
}
h3 {
  margin-top: 0;
  color: #0f766e;
}
</style>

Page-Level Information Applied to Items

<div id="site-metadata">
<meta itemprop="inLanguage" content="en-US">
<meta itemprop="copyrightYear" content="2025">
</div>

<div itemscope itemtype="http://schema.org/WebPage"
   itemref="site-metadata">
<h1 itemprop="name">Product Catalog</h1>
<div itemprop="mainEntity" itemscope
     itemtype="http://schema.org/ItemList">
  <div itemprop="itemListElement" itemscope
       itemtype="http://schema.org/Product">
    <span itemprop="name">Wireless Headphones</span>
    <span itemprop="price">$99.99</span>
  </div>
  <div itemprop="itemListElement" itemscope
       itemtype="http://schema.org/Product">
    <span itemprop="name">Bluetooth Speaker</span>
    <span itemprop="price">$149.99</span>
  </div>
</div>
</div>

<style>
[itemtype*="WebPage"] {
  border: 2px solid #f59e0b;
  padding: 20px;
  border-radius: 8px;
  background: #fffbeb;
}
[itemtype*="Product"] {
  display: flex;
  justify-content: space-between;
  padding: 12px;
  margin: 8px 0;
  background: white;
  border-radius: 4px;
  border: 1px solid #fcd34d;
}
</style>

Result

Interactive code playground requires JavaScript. Here's the code:

<div id="site-metadata">
<meta itemprop="inLanguage" content="en-US">
<meta itemprop="copyrightYear" content="2025">
</div>

<div itemscope itemtype="http://schema.org/WebPage"
   itemref="site-metadata">
<h1 itemprop="name">Product Catalog</h1>
<div itemprop="mainEntity" itemscope
     itemtype="http://schema.org/ItemList">
  <div itemprop="itemListElement" itemscope
       itemtype="http://schema.org/Product">
    <span itemprop="name">Wireless Headphones</span>
    <span itemprop="price">$99.99</span>
  </div>
  <div itemprop="itemListElement" itemscope
       itemtype="http://schema.org/Product">
    <span itemprop="name">Bluetooth Speaker</span>
    <span itemprop="price">$149.99</span>
  </div>
</div>
</div>

<style>
[itemtype*="WebPage"] {
  border: 2px solid #f59e0b;
  padding: 20px;
  border-radius: 8px;
  background: #fffbeb;
}
[itemtype*="Product"] {
  display: flex;
  justify-content: space-between;
  padding: 12px;
  margin: 8px 0;
  background: white;
  border-radius: 4px;
  border: 1px solid #fcd34d;
}
</style>

How It Works

For itemref to work correctly:

The element must have itemscope: The itemref attribute is only valid on elements that define an item scope.
Referenced elements must exist: Each ID in the itemref value must correspond to an element in the document.
Referenced elements contain itemprop: The referenced elements (or their descendants) should have itemprop attributes that define properties for the item.

<!-- The item with itemscope and itemref -->
<div itemscope itemtype="http://schema.org/Movie" itemref="director cast">
  <h1 itemprop="name">The Matrix</h1>
  <span itemprop="datePublished">1999</span>
</div>

<!-- Referenced element with additional properties -->
<div id="director">
  <span itemprop="director" itemscope itemtype="http://schema.org/Person">
    <span itemprop="name">Lana Wachowski</span>
  </span>
</div>

<!-- Another referenced element -->
<div id="cast">
  <span itemprop="actor" itemscope itemtype="http://schema.org/Person">
    <span itemprop="name">Keanu Reeves</span>
  </span>
</div>

Multiple References

You can reference multiple elements by separating their IDs with spaces:

<div itemscope itemtype="http://schema.org/Recipe"
   itemref="ingredients instructions nutrition">
<h2 itemprop="name">Chocolate Chip Cookies</h2>
<p itemprop="description">Classic homemade cookies</p>
</div>

<div id="ingredients">
<h3>Ingredients</h3>
<span itemprop="recipeIngredient">2 cups flour</span>,
<span itemprop="recipeIngredient">1 cup sugar</span>,
<span itemprop="recipeIngredient">1 cup chocolate chips</span>
</div>

<div id="instructions">
<h3>Instructions</h3>
<p itemprop="recipeInstructions">
  Mix dry ingredients, add wet ingredients, fold in chips, bake at 350°F.
</p>
</div>

<div id="nutrition">
<h3>Nutrition</h3>
<meta itemprop="calories" content="180">
<p>180 calories per serving</p>
</div>

<style>
[itemscope] {
  border: 2px solid #ef4444;
  padding: 16px;
  border-radius: 8px;
  background: #fef2f2;
  margin-bottom: 12px;
}
[id] {
  border: 1px dashed #f87171;
  padding: 12px;
  margin: 8px 0;
  border-radius: 4px;
  background: #fff5f5;
}
h3 {
  margin-top: 0;
  color: #dc2626;
}
</style>

Result

Interactive code playground requires JavaScript. Here's the code:

<div itemscope itemtype="http://schema.org/Recipe"
   itemref="ingredients instructions nutrition">
<h2 itemprop="name">Chocolate Chip Cookies</h2>
<p itemprop="description">Classic homemade cookies</p>
</div>

<div id="ingredients">
<h3>Ingredients</h3>
<span itemprop="recipeIngredient">2 cups flour</span>,
<span itemprop="recipeIngredient">1 cup sugar</span>,
<span itemprop="recipeIngredient">1 cup chocolate chips</span>
</div>

<div id="instructions">
<h3>Instructions</h3>
<p itemprop="recipeInstructions">
  Mix dry ingredients, add wet ingredients, fold in chips, bake at 350°F.
</p>
</div>

<div id="nutrition">
<h3>Nutrition</h3>
<meta itemprop="calories" content="180">
<p>180 calories per serving</p>
</div>

<style>
[itemscope] {
  border: 2px solid #ef4444;
  padding: 16px;
  border-radius: 8px;
  background: #fef2f2;
  margin-bottom: 12px;
}
[id] {
  border: 1px dashed #f87171;
  padding: 12px;
  margin: 8px 0;
  border-radius: 4px;
  background: #fff5f5;
}
h3 {
  margin-top: 0;
  color: #dc2626;
}
</style>

Best Practices

Use When Necessary

Only use itemref when your document structure genuinely requires properties to be separate. Prefer nesting properties within the itemscope element when possible:

<!-- Preferred: nested structure -->
<div itemscope itemtype="http://schema.org/Person">
  <span itemprop="name">Jane Doe</span>
  <span itemprop="email">[email protected]</span>
</div>

<!-- Use itemref only when structure demands it -->
<div itemscope itemtype="http://schema.org/Person" itemref="contact">
  <span itemprop="name">Jane Doe</span>
</div>
<footer id="contact">
  <span itemprop="email">[email protected]</span>
</footer>

Ensure IDs Are Unique

Since itemref relies on ID references, make sure each ID is unique in the document:

<!-- Correct -->
<div itemscope itemref="bio-1">...</div>
<div id="bio-1">...</div>

<div itemscope itemref="bio-2">...</div>
<div id="bio-2">...</div>

Document Your Structure

When using itemref, add comments to explain the relationship between elements:

<!-- Product item references warranty and shipping info -->
<div itemscope itemtype="http://schema.org/Product"
     itemref="warranty shipping">
  <h2 itemprop="name">Laptop Computer</h2>
</div>

<!-- Warranty information (referenced by itemref) -->
<div id="warranty">
  <meta itemprop="warranty" content="2 years">
</div>

<!-- Shipping information (referenced by itemref) -->
<div id="shipping">
  <meta itemprop="shippingDetails" content="Free shipping">
</div>

Browser Support

The itemref attribute is part of the HTML5 Microdata specification and is supported by all modern browsers. However, Microdata extraction and processing is primarily done by search engines and other automated tools rather than browsers directly.

Browser	Support
Chrome	Yes (HTML5 Microdata)
Firefox	Yes (HTML5 Microdata)
Safari	Yes (HTML5 Microdata)
Edge	Yes (HTML5 Microdata)

itemscope

Defines an item scope for Microdata. Required for using itemref.

itemtype

Specifies the vocabulary URL that defines the item’s properties.

itemprop

Defines a property of an item within an itemscope.

itemid

Provides a unique identifier for an item within a vocabulary.

itemref - Reference External Properties

The itemref Attribute

Quick Example

Syntax

Values

Why Use itemref?

Common Use Cases

Author Information in a Separate Section

Shared Metadata Across Multiple Items

Page-Level Information Applied to Items

How It Works

Multiple References

Best Practices

Use When Necessary

Ensure IDs Are Unique

Document Your Structure

Browser Support

Related Attributes

Specifications

The `itemref` Attribute

Why Use `itemref`?