Message Rendering Pipeline#

Element Web processes message content (m.text, m.emote, m.notice) through a multi-stage sanitization and transformation pipeline before display. The main stages are:

1. Sanitization — HTML is cleaned through sanitize-html using a strict allowlist
2. Tag transformation — mxc:// URLs are resolved, inline images capped, and colors converted
3. Post-render DOM work — linkification, pills, spoilers, and syntax highlighting applied after mount

TextualBody.render()
  └── HtmlUtils.bodyToDiv / bodyToSpan
        └── bodyToNode → analyseEvent
              ├── sanitizeHtml(formattedBody, sanitizeHtmlParams)
              │ └── transformTags (img, a, code, *)
              └── formatEmojis (after sanitization)
  └── TextualBody.applyFormatting() [componentDidMount]
        ├── activateSpoilers
        ├── linkifyElement
        ├── pillifyLinks
        ├── calculateUrlPreview
        ├── tooltipifyLinks
        └── highlightCode (async)

Key source files:

HTML Sanitization#

The canonical sanitization configuration is sanitizeHtmlParams in Linkify.tsx, used whenever a formatted_body with format: "org.matrix.custom.html" is present 1.

Allowed tags follow the Matrix spec 2: font, del, h1–h6, blockquote, p, a, ul, ol, li, b, i, u, strong, em, strike, code, hr, br, div, table, thead, tbody, tr, th, td, pre, span, img, details, summary. Tags not in this list (script, iframe, style, object, etc.) are stripped entirely.

Allowed attributes are specified per tag 3:

• font: color, data-mx-bg-color, data-mx-color, style
• span: data-mx-maths, data-mx-bg-color, data-mx-color, data-mx-spoiler, style
• a: href, name, target, rel
• img: src, alt, title, style

Allowed URL schemes come from PERMITTED_URL_SCHEMES — an allowlist of ~25 schemes including http, https, matrix, mailto, irc, ssh, tel, etc. Protocol-relative URLs are blocked (allowProtocolRelative: false) 4. Nesting is capped at 50 levels deep 5.

Variant configs 6:

• composerSanitizeHtmlParams — same allowedTags/attrs but only the code and * transformTags, used when quoting into the composer
• topicSanitizeHtmlParams — stripped-down tag set (no headings, tables, or images) for room topics

Tag Transformation & mxc:// URL Conversion#

transformTags runs before attribute filtering during sanitization. It has four handlers:

"img" — inline image processing#

This is the most security-sensitive transform 7:

1. If the showImages account setting is false, the image is dropped entirely (empty attribs returned) 8.
2. If src doesn't already start with mxc://, MEDIA_API_MXC_REGEX tries to convert a Matrix Media API HTTP URL (/_matrix/media/r0/(download|thumbnail)/{server}/{id}) back to mxc:// form 9.
3. If src is still not mxc://, the image is dropped — no external HTTP image sources are permitted 10.
4. Width/height are capped at 800×600 px and written as max-width/max-height CSS 11.
5. The final src is resolved via mediaFromMxc(src).getThumbnailOfSourceHttp(width, height), which calls Media.getThumbnailOfSourceHttp — scaling by window.devicePixelRatio and calling client.mxcUrlToHttp(mxc, w, h, "scale") to produce a /media/v3/thumbnail/… HTTP URL.

"a" — external link handling#

Adds target="_blank" to all links by default, then removes it for Matrix permalink hosts (e.g. matrix.to) and Element domain links. Always adds rel="noreferrer noopener" 12.

"code" — class filtering#

Strips all classes except those matching language-* (for syntax highlighting), and excludes language-_* 13.

"*" — color attributes#

Deletes any pre-existing style attribute (except on img). Converts data-mx-color and data-mx-bg-color to inline CSS color / background-color, validating values against #[0-9a-fA-F]{6} 14.

Emoji & Big Emoji#

Emoji rendering runs after HTML sanitization in bodyToNode.

EMOJI_REGEX uses Unicode v-mode \p{RGI_Emoji} sequences (with a safe fallback to /(?!)/ on unsupported platforms). formatEmojis() segments the message string via graphemeSegmenter and wraps each emoji in a <span class="mx_Emoji" title=":shortcode:">. Two output modes exist: HTML strings (for dangerouslySetInnerHTML paths) and JSX elements (for plain text paths).

Big emoji: if the entire trimmed message body (after stripping zero-width joiners and spaces) matches BIGEMOJI_REGEX and the message contains no HTTP links, the body gets the mx_EventTile_bigEmoji CSS class for oversized display 15. This is suppressed for emote messages or if the TextualBody.enableBigEmoji setting is off 16.

LaTeX: if feature_latex_maths is enabled, data-mx-maths attributes in <div> and <span> are rendered via katex.renderToString before emoji processing 17.

Custom Emoticons (MSC2545)#

MSC2545 defines im.ponies.room_emotes / m.room.image_pack room state events for custom image emoticon packs. Element has basic receiving support: it can render inline custom emoticons sent by other clients (Cinny, FluffyChat, Nheko). 18

The rendering goes through the same img transform path in transformTags — the emoticon's mxc:// URL is resolved to a thumbnail HTTP URL via getThumbnailOfSourceHttp. No dedicated data-mx-emoticon attribute handling exists in matrix-react-sdk; the standard <img> sanitization pipeline handles display. 7

Known limitation: animated GIF emoticons render as a static single frame. The root cause is the thumbnail-fallback behavior in getThumbnailOfSourceHttp (which requests a scaled/static thumbnail instead of the original animated file), the same issue as regular pasted GIFs (#32311). This is tracked in element-web issue #34339. 18

Post-Sanitization DOM Processing#

After render() mounts the sanitized HTML, applyFormatting() runs a series of DOM passes in order:

1. activateSpoilers — walks the DOM for [data-mx-spoiler] spans and replaces them with <Spoiler> React components (rendered via ReactDOM.render into placeholder nodes).
2. linkifyElement — linkifies plain-text URLs in the DOM (wraps them in <a> elements) using linkify-react with Matrix-specific options from linkify-matrix.
3. pillifyLinks — converts Matrix mention links into interactive user/room pill components.
4. calculateUrlPreview — collects previewable <a> href values from the DOM (deduplicated via Set, skipping <pre>/<code>/<blockquote> descendants and Matrix permalink hosts) and stores them in state to trigger LinkPreviewGroup rendering.
5. tooltipifyLinks — adds tooltip overlays to pill links; runs after calculateUrlPreview so it doesn't interfere with anchor discovery.
6. Code block enhancement (HTML messages only, 19): wraps <pre> elements in a container div, adds expand/collapse and copy buttons, and asynchronously invokes highlight.js for syntax highlighting. Highlight is skipped for blocks > 4096 characters 20.