How to Create, Display, and Edit Rich Text Metafields in Shopify

A rich text metafield is a Shopify metafield type that stores formatted text, including headings, lists, links, bold and italics. It’s useful for content such as product details, care instructions, FAQs or author bios that needs more structure than plain text but should still vary from product to product.

You create a rich text metafield definition, enter formatted content on each product and show it on your store through a theme block or Liquid. Knowing how the format works also helps you avoid common issues, such as raw code appearing on product pages.

What Is a Rich Text Metafield?

In Shopify, the rich text metafield type is called rich_text_field. It supports headings, paragraphs, ordered and unordered lists, links, bold and italic text, and it’s translatable for stores that sell in several languages.

Behind the scenes, Shopify stores rich text as structured JSON rather than HTML. The admin editor handles this for you, but the format matters when you display the field with code or update it in bulk.

Rich text sits between simpler and more flexible content options. This comparison shows when to use each:

How to Create a Rich Text Metafield

You create a rich text metafield by adding a definition for the resource you want, such as products or collections. Follow these steps in your Shopify admin:

1. Go to Settings > Metafields and metaobjects and select the resource, such as Products.
2. Click Add definition.
3. Enter a name, such as “Care instructions,” and adjust the namespace and key if needed, such as custom.care_instructions.
4. Click Select type and choose Rich text.
5. Optionally, add a description so staff know what to enter.
6. Click Save.

Rich text doesn’t have a list version, so each definition holds one block of formatted content. If you need several separate items, such as individual FAQ questions, create a separate metafield for each one or use a metaobject.

How to Add Content to a Rich Text Metafield

Open a product, scroll to the Metafields section and click the rich text field. The editor lets you add headings, bold and italic text, bulleted or numbered lists and links, then save the product.

Keep the content focused on what makes each product different. Shared content that’s identical across many products is easier to manage in a page or metaobject, since you update it once instead of on every product.

How to Display a Rich Text Metafield on Your Store

Once products have content, connect the metafield to your theme so it appears on the storefront. There are two main approaches, depending on your theme and how much control you need.

Connect it in the theme editor

In the theme editor, open your product template and add a block that supports rich content, such as a rich text block or collapsible row. Click the dynamic source icon, choose your rich text metafield and save.

Not every block accepts every metafield type, so the field may not appear in the dynamic source list for some blocks. If that happens, try another block type or use the Liquid method instead.

Output it with Liquid

To display a rich text metafield in code, add a Custom Liquid block or edit your theme files and use the metafield_tag filter. Apply the filter to the metafield itself, not to its .value:

{% if product.metafields.custom.care_instructions %}
 {{ product.metafields.custom.care_instructions | metafield_tag }}
{% endif %}

The filter converts the stored JSON into HTML, wrapped in a div with the class metafield-rich_text_field. Outputting the field without the filter can print raw JSON instead of formatted text, and applying the filter to .value causes an error.

If you only want plain text, some themes strip the formatting with the strip_html filter. That removes headings, lists and bold text, so use it only when formatting isn’t needed.

Render it in a headless storefront

Headless storefronts receive rich text as JSON through the Storefront API rather than as HTML. In Hydrogen, the RichText component renders this JSON as semantic HTML and lets you customize how each element, such as paragraphs or headings, is displayed.

For other frameworks, you’ll need to convert the JSON into HTML yourself or use a library that does it. Enable storefront access on the metafield definition so the Storefront API can read the value.

Rich Text Metafield JSON Format

Understanding the JSON format helps when you update rich text through the API or an import tool. Every value starts with a root node that contains paragraphs, headings and lists:

{
 "type": "root",
 "children": [
 {
 "type": "heading",
 "level": 3,
 "children": [{ "type": "text", "value": "Care instructions" }]
 },
 {
 "type": "paragraph",
 "children": [
 { "type": "text", "value": "Machine wash cold. ", "bold": true },
 {
 "type": "link",
 "url": "https://example.com/care",
 "title": "Full care guide",
 "children": [{ "type": "text", "value": "See the full guide" }]
 }
 ]
 }
 ]
}

Text nodes can be marked as bold or italic, links need a URL and can include a title, and lists use a listType of ordered or unordered with list items inside. Through the GraphQL Admin API, the whole JSON object is sent and stored as a string.

Bulk Edit Rich Text Metafields

Editing rich text one product at a time gets slow in larger catalogs. Shopify’s product CSV supports many metafield types, but rich text isn’t on its list of supported types, so bulk updates usually go through an app or the API.

Some bulk editing apps accept HTML and convert it into Shopify’s rich text JSON for you. These conversions typically support a limited set of tags:

• Headings: <h1> to <h6>
• Paragraphs and line breaks: <p> and <br>
• Bold and italic: <strong>, <b>, <em> and <i>
• Links: <a>
• Lists: <ul>, <ol> and <li>

Unsupported tags are usually stripped during conversion, and top-level content should be paragraphs or lists. Test a few products first and check how the content looks on the storefront before updating your whole catalog.

Common Uses for Rich Text Metafields

Rich text works well wherever product-specific content needs structure. Common examples include:

• Care and usage instructions. Short steps or bullet points for each product.
• Ingredients and materials. Lists with bold callouts for allergens or key components.
• Product highlights. A few formatted bullet points shown near the add to cart button.
• Author or designer bios. A formatted paragraph with links to related collections.
• Collection introductions. Formatted text at the top or bottom of a collection page.

Collapsible rows or tabs below the main product information are a common place to show this content. They keep product pages tidy while still giving shoppers the details they need.

Common Rich Text Metafield Problems

Many rich text issues come from how the field is displayed or imported. Watch for these:

• Raw JSON appears on the page. The metafield was output without the metafield_tag filter.
• Liquid error with metafield_tag. The filter was applied to .value instead of the metafield itself.
• The metafield isn’t in the dynamic source list. The block doesn’t support rich text, so try a different block or Custom Liquid.
• Formatting disappears. The theme or custom code uses strip_html, which removes all formatting.
• Imported content looks different. Unsupported HTML tags were stripped during conversion.
• Tables or images don’t work. Rich text doesn’t support them, so use a page reference metafield for that content.

Conclusion

A rich text metafield gives you a simple way to add formatted, product-specific content without editing every product description by hand. With the right definition, a compatible theme block or the metafield_tag filter, your content displays cleanly and stays easy to update. We hope this guide helps you set up and use a rich text metafield in your store with confidence.