Rule.io SDK

---

Rule.io SDK / rcml/src / applyTheme

Function: applyTheme()

applyTheme(doc, theme): RcmlDocument

Defined in: rcml/src/email/apply-theme.ts:78

Apply a theme or a partial patch to an RCML document. The input doc is not mutated; a new RcmlDocument is returned.

Every bucket uses overlay semantics: for each entry the caller provides, the matching rcml node is upserted (updated if present, created if missing). Entries the caller does not mention are left alone. This means:

• Pass a full EmailTheme → every bucket's every sub-slot is present, so every theme-controlled node is upserted. The doc ends up matching the theme, but any orphan custom nodes that aren't part of the theme's vocabulary survive.
• Pass a partial EmailThemePatch (e.g. { colors: [{ type: Primary, hex: '#F00' }] }) → only rc-button's background-color is touched. rc-body, rc-section, the rcml-brand-color class, rc-social, rc-font etc. are untouched.
• Pass an empty bucket (e.g. { colors: [] }) → no-op for that bucket. applyTheme never removes nodes; there's no explicit "clear" verb.

Works uniformly on:

• Docs with no theme yet (missing head nodes get created).
• Docs with the default theme applied (node identity preserved; ids kept).
• Docs with a different custom theme (same upsert-only behaviour).

Parameters

doc

RcmlDocument

The document to theme. Not mutated.

theme

EmailTheme | EmailThemePatch

Either a full EmailTheme or a partial EmailThemePatch.

Returns

RcmlDocument

A new RcmlDocument with the theme applied.

Throws

EmailThemeApplyError when a URL (logo src, social href, font href) fails safety validation.