HTML Block

Place custom HTML inside an option set — size charts, care instructions, promo banners, tables, and links — written directly as markup in a code editor.

Formerly "Descriptive Text"

HTML Block is the same option type Descriptive Text used to be, renamed and upgraded with a real HTML editor. Existing Descriptive Text options were moved over automatically — you don't need to recreate anything, and your saved content is unchanged. See Descriptive Text for the full note.

If you'd rather format content without writing markup, use Rich Text instead.

Overview

HTML Block is a display-only option type. Customers can read it but never interact with it, and it contributes nothing to the cart.

Use HTML Block for:

• Size and specification tables
• Care instructions and washing symbols
• Promotional banners with custom styling
• Disclaimers, policies, and legal notices
• Links to guides, policy pages, or FAQs

Key characteristics:

• Raw HTML, authored in a syntax-highlighted code editor
• Up to 8,000 characters of markup, with a live counter
• Cannot be marked as required — it collects nothing
• Content is sanitized twice: on save, and again when rendered
• Cannot trigger a condition, but can be shown or hidden by one

Configuration

Basic Settings

Setting	Description
Label	Option name (shown in admin and optionally on the storefront)
Hide Label from storefront	If enabled, only the HTML content is shown

No "Required" checkbox

HTML Block is display-only — it submits no value, so requiring it would mean nothing. The checkbox is hidden for this type, the same as for Spacing, Divider, Heading, Accordion, Tabs, and Rich Text.

HTML Content

Setting	Options (default)	What it controls
HTML Content	HTML markup, max 8,000 characters (empty)	The markup rendered on the product page. In-app help: Basic HTML is supported — links, lists, bold, and inline styles.

The editor is a code editor only — there's no visual/WYSIWYG mode. It gives you HTML syntax highlighting and wraps long lines, so you never scroll sideways to read your markup. A live character counter sits below the field.

Advanced Settings

Setting	Description
Internal Label	Admin-only identifier (replaces label in the options list)
Help Text	Additional guidance shown to customers (based on display mode)
CSS class / CSS ID	Your own selectors on this option's container — see CSS Class & CSS ID

Validation

Message	Cause
Value is required	HTML Content is empty, or contains only whitespace
This content is too long. Shorten it to save.	Markup exceeds 8,000 characters

The 8,000-character limit counts the markup, not the visible text — tags, attributes, and inline styles all count toward it.

How to Add an HTML Block

1. Navigate to Option Sets and open your option set
2. Click Add Option
3. Select HTML Block from the Option Type modal (it's under the Static category)
4. Enter a Label, or enable Hide Label from storefront for a bare content block
5. Write your markup in HTML Content, watching the character counter
6. (Optional) Click Advanced Settings for an Internal Label, Help Text, or a CSS class/ID
7. Click Save in the contextual save bar

What HTML Is Allowed

Your markup passes through a sanitizer when you save it, and through the same allowlist again when the storefront renders it. Anything not on the list below is removed.

Allowed tags

Group	Tags
Text	p, br, span, div, h1–h6, blockquote, hr, small, sub, sup, code, pre
Emphasis	b, strong, i, em, u, s, del, ins, mark
Lists	ul, ol, li, dl, dt, dd
Tables	table, thead, tbody, tfoot, tr, td, th, caption, colgroup, col
Links & figures	a, figure, figcaption

Allowed attributes

href, target, rel, title, class, style, data-url, colspan, rowspan, scope, lang, dir

Accessibility and internationalization are covered

lang and dir are allowed specifically so multi-language stores can mark a language change (screen readers switch pronunciation) and lay out right-to-left content correctly. scope, colspan, and rowspan keep data tables readable to assistive technology.

What gets stripped

Removed	Why
<script> and its contents	Script execution
onclick, onerror, onmouseover and every other on* handler	Script execution
<iframe>, <object>, <embed>, <form>, <input>, <style>	Embedding, data capture, and page-wide style hijacking
<img>	Images are not supported in HTML Block at all — see the warning below
href="javascript:..."	Only http, https, mailto, tel, and relative links survive

Images aren't supported

<img> is not on the allowlist, so every image tag is removed — not just malicious ones. An HTML Block can't display images. Use a Swatch or an Image Dropdown where you need imagery, or raise it with support if your use case needs images in static content.

Inline CSS is filtered per declaration

style and class are both allowed, so you can style a block inline. But individual CSS declarations are checked, and dangerous ones are dropped while the rest of the rule survives:

<!-- What you write -->
<p style="background:url(https://example.com/track.png); color:red;">Styled</p>

<!-- What renders -->
<p style="color:red;">Styled</p>

Declarations containing javascript:, vbscript:, expression(...), behavior:, -moz-binding, @import, or url(...) are removed whole. Everything else is kept.

url(...) is always dropped — including legitimate ones

The filter can't tell a background image from a tracking pixel, so any declaration using url() is removed. background-image, list-style-image, and custom fonts referenced by URL will not work in an HTML Block. Partial survival like the example above is correct behavior, not a bug.

Links that open in a new tab are hardened

Any <a target="_blank"> automatically gains rel="noopener noreferrer", whether or not you write it. This stops the opened page from reaching back into the store window.

Conditions

HTML Block cannot be selected as a condition trigger — it has no value for a rule to test. It can, however, be the target of another option's condition, so you can show a size chart only when a particular size is chosen, or hide a disclaimer for certain products.

See Setting Up Conditions.

Cart and Orders

HTML Block contributes no line-item property. Nothing about it appears in the cart, at checkout, or on the order — it's presentation only.

Examples

Size chart

<table>
  <caption>Size chart</caption>
  <thead><tr><th scope="col">Size</th><th scope="col">Chest</th></tr></thead>
  <tbody>
    <tr><td>S</td><td>90 cm</td></tr>
    <tr><td>M</td><td>98 cm</td></tr>
    <tr><td colspan="2">Measurements are approximate</td></tr>
  </tbody>
</table>

Care instructions with links

<h3>Care instructions</h3>
<p>Wash <strong>cold</strong>, <em>do not</em> tumble dry.</p>
<p>See our <a href="/pages/care-guide" title="Care guide">care guide</a> or
<a href="https://example.com" target="_blank">the fabric spec</a>.</p>

Promo banner with inline styling

<div class="promo" style="background:#f4f6f8; padding:12px; border-radius:8px;">
  <p style="color:#008060; font-weight:600;">Free shipping over €50</p>
</div>

Multi-language content

<p>Bonjour <span lang="fr">enchanté</span></p>
<p dir="rtl">مرحبا بكم</p>

Best Practices

Write it, then check it on the storefront:

• The sanitizer runs on save, so what you typed and what's stored can differ
• Reopen the option after saving to see exactly what survived
• Test on a real product page, not just the editor

Keep blocks focused:

• One subject per block reads better and is easier to target with conditions
• Long documents belong on a linked page, not in an option set
• Remember the 8,000-character budget counts markup, so tables consume it fast

Prefer classes over heavy inline styles:

• Add a class and style it from your theme where you can
• Inline styles are allowed, but url() never survives
• See CSS Class & CSS ID

Use the right type for the job:

• If you're not writing markup by hand, Rich Text is easier
• For a plain title, use Heading
• For a visual break, use Divider or Spacing

Troubleshooting

My tags show as literal text: The content saved as escaped text rather than markup. Confirm the option type is HTML Block, not a text input type

My image disappeared: Expected — <img> is never allowed. See the warning above

My background image doesn't show: url(...) is stripped from inline CSS. Move the rule into your theme's stylesheet and target the block with a CSS class

Can't save — "This content is too long": The markup is over 8,000 characters. Trim attributes and whitespace, or split into two blocks

Can't save — "Value is required": The field is empty or whitespace-only

My <script> vanished: Working as designed, on both save and render

Related

• Rich Text — the same purpose, authored visually instead of in code
• Descriptive Text — what happened to the old option type
• Heading — a simple title without markup
• Divider and Spacing — visual separation
• CSS Class & CSS ID — target this block from your theme CSS
• Setting Up Conditions — show or hide a block conditionally