Variants in Dyspatch - Scaling your Email Designs

What are Variants in Dyspatch?

Variants let you set up several pre-approved styles for the same element inside one theme. Think of it as a style library: bold or minimal text, default or error buttons, etc. This keeps emails on-brand while giving your team flexible, ready-to-use options.

How to Use Variants

Define Variants in Your Theme

In your Theme, navigate to the Advanced tab to view your theme code, create a base element (the default style) and add variants. Give each variant a unique name and its own styles.

Apply Variants to Blocks

When building a block, use the variant="name" attribute on an element to apply one of your pre-set styles.

Edit Variants in the Email Builder

Add the editable attribute so users can switch between variants right inside the email builder.

Understanding Style Precedence

When more than one style is defined for the same element, Dyspatch decides which one to use based on the following order: editable style → variant → block → theme

1. Editable styles: user changes in the email builder override everything.
2. Variant styles: pre-set variant styles override default elements.
3. Block defaults: attributes defined on the block.
4. Theme defaults: base element style in the theme.

Locked-Down Themes

If your theme is locked, make sure editable-styles is enabled for users to change variants.

Best Practices

For Theme Developers

• Plan ahead: If builders often change spacing, fonts, or colors, create variants for those cases.
• Keep it curated: Only add variants that fit your brand system; don’t overload your theme.
• Name clearly: Use descriptive names like "button-secondary" or "card-highlight" so it’s obvious what each does.

For Block Builders

• Use variants first: Don’t rely on manual overrides. Variants reset block-level settings to the theme baseline, which is good!
• Request new variants: If you keep making the same tweak, ask your theme team to add a variant for it.

For Email Builder Users

• Switch carefully: Changing variants can remove your custom block edits.
• Always preview: Check your email before publishing to make sure the styling looks right.