Skip to content

HTML Policy

The html_policy field controls how raw HTML inside a board's text: blocks is handled. By default, dbt charts escapes HTML as plain text. You can opt into raw HTML rendering by setting html_policy at the board root.

Tiers

Value What it allows When to use
none HTML is escaped and rendered as plain text. Default. No raw HTML reaches the browser.
safe-subset Reserved for a parser-checked allowlist. Not yet enforced — currently renders as none. Do not use in current releases; future enforcement will differ from today's behavior.
trusted-raw A fixed set of structural, inline, list, table, and media tags passed through a parser-based sanitizer. Layouts or widgets that Markdown cannot express, on dashboards you fully control.

A deployment can cap the effective tier below what the board requests — Cloud, for example, caps at safe-subset. A compile-time warning fires when this happens.

none (default)

HTML in a text: block is escaped and shown as literal characters:

text: |
  Revenue grew **15%** quarter-over-quarter.
  <strong>bold?</strong> — these tags print as text, not HTML.

trusted-raw

Set at the board root to render text: as raw HTML:

html_policy: trusted-raw
text: |
  <div style="display: flex; gap: 16px; align-items: center;">
    <span style="font-size: 2rem; font-weight: 700;">$4.2M</span>
    <span style="color: #16a34a;">+15% QoQ</span>
  </div>

What passes through

trusted-raw runs HTML through a parser-based allowlist. Only an enumerated set of tags is allowed; everything else is dropped. The allowed set covers:

  • Structural: div, span, section, article, aside, header, footer, main, nav, details, summary
  • Headings: h1 through h6
  • Inline: p, a, strong, em, code, mark, abbr, time, and their semantic siblings
  • Lists: ul, ol, li, dl, dt, dd
  • Tables: table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col
  • Media: img, figure, figcaption
  • Preformatted: pre, blockquote, hr

Tags not on this list — including <script>, <iframe>, <video>, <canvas>, <svg>, <input>, and <style> — are dropped entirely. The parser walk also closes javascript: hrefs and unquoted event handlers, so those vectors are not available even on allowed tags.

The one residual risk: inline style attributes pass through without CSS parsing. An author can write style="position:fixed" and it takes effect. This is by design — trusted-raw is sanitized HTML, not a sandbox — but it means HTML you did not author can manipulate page layout. Review text: blocks in boards you import.

When to use trusted-raw

Use it only when all of these are true:

  • The board is a first-party dashboard you authored and control.
  • No text: block contains user-supplied values or dashboard variables you have not reviewed.
  • The HTML layout or widget you need cannot be expressed in Markdown.

Why the tier is named trusted-raw

The name states the requirement up front: this is raw HTML that you are declaring trustworthy. A name like allow_html reads as a plain feature toggle; trusted-raw is the assertion you are making when you enable it. Streamlit's unsafe_allow_html follows the same naming intent — the risk is in the name, not in a docstring you might not read first.

safe-subset — forthcoming

safe-subset is reserved for a future release that will enforce a stricter allowlist (no inline style, tighter attribute set). Until that enforcement ships, safe-subset behaves identically to none — it does not route to raw HTML rendering. Do not rely on it for HTML output today.

Inheritance and scope

html_policy is a root-level field. It applies to the board that declares it and is not inherited by nested boards. A nested board that needs raw HTML must declare its own html_policy: trusted-raw.

# Root sets trusted-raw
html_policy: trusted-raw
text: |
  <strong>Root-level raw HTML works.</strong>

rows:
  - text: |
      <strong>This nested board did NOT inherit html_policy —
      the tags above print as text.</strong>
  • Content — Markdown text blocks, images, tables, and callouts
  • Boards — Board structure and layout
  • YAML Reference — html_policy field entry