Display Conditions

Display conditions let your users control which blocks appear in an email based on recipient data. For example, a "VIP Offer" block can be shown only to premium customers, or a "Renewal Reminder" block only to users whose subscription is expiring.

How It Works

1. You configure the available conditions with descriptive labels and before/after wrapping strings
2. Your users select a condition from a dropdown in the block toolbar
3. At export, the SDK wraps the block's HTML with the before and after strings
4. Your sending platform evaluates the conditions and shows/hides blocks per recipient

The SDK itself doesn't evaluate conditions — it provides the UI for selecting them and wraps the HTML at export time. Your email sending platform (Liquid, Handlebars, Mailchimp, etc.) handles the actual conditional logic.

Configuration

Pass display conditions through the displayConditions option in init():

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  displayConditions: {
    conditions: [
      {
        label: 'VIP customers only',
        before: '{% if customer.vip %}',
        after: '{% endif %}',
        group: 'Customer',
        description: 'Only shown to customers with VIP status.',
      },
      {
        label: 'Free plan users',
        before: '{% if customer.plan == "free" %}',
        after: '{% endif %}',
        group: 'Customer',
        description: 'Targets users on the free plan tier.',
      },
      {
        label: 'Has purchased before',
        before: '{% if customer.orders_count > 0 %}',
        after: '{% endif %}',
        group: 'Customer',
      },
    ],
    allowCustom: true,
  },
});

Top-level properties:

Property	Type	Description
conditions	DisplayCondition[]	Array of preset display conditions
allowCustom	boolean?	When true, users can write their own before/after logic (default: false)

Condition properties:

Property	Type	Description
label	string	Human-readable name shown in the toolbar dropdown
before	string	Markup inserted before the block in exported HTML
after	string	Markup inserted after the block in exported HTML
group	string?	Optional grouping for organizing conditions in the dropdown
description	string?	Plain-language explanation shown below the condition label

Description Field

The optional description field provides a human-readable explanation of what a condition does. When a condition is applied to a block, the description is shown as muted text below the condition label in the toolbar. This helps users understand the effect of each condition without needing to read the underlying logic.

Custom Conditions

When allowCustom: true is set, a "Custom condition" option appears at the bottom of the condition dropdown. Selecting it opens a form where users can:

1. Name their condition (a descriptive label)
2. Write the before markup (the opening conditional logic)
3. Write the after markup (the closing conditional logic)

Custom conditions are stored on the block identically to preset conditions. They appear with a "Custom" badge in the toolbar to distinguish them from presets. This is useful for power users who need conditions not covered by the presets you provide.

Grouping Conditions

Use the optional group property to organize conditions into logical categories in the dropdown. Conditions with the same group value appear under a shared heading:

displayConditions: {
  conditions: [
    // These appear under "Customer" heading
    { label: 'VIP customers', before: '{% if customer.vip %}', after: '{% endif %}', group: 'Customer' },
    { label: 'New customers', before: '{% if customer.new %}', after: '{% endif %}', group: 'Customer' },

    // These appear under "Location" heading
    { label: 'US recipients', before: '{% if contact.country == "US" %}', after: '{% endif %}', group: 'Location' },
    { label: 'EU recipients', before: '{% if contact.region == "EU" %}', after: '{% endif %}', group: 'Location' },
  ],
},

Conditions without a group appear ungrouped at the top of the dropdown.

Visual Indicators

When a display condition is applied to a block:

• A filter icon badge appears on the block in the editor canvas
• The toolbar shows the active condition name with a remove button
• Users can change or remove the condition at any time

Platform Examples

Liquid / Shopify

displayConditions: {
  conditions: [
    {
      label: 'VIP customers',
      before: '{% if customer.tags contains "vip" %}',
      after: '{% endif %}',
    },
  ],
},

Handlebars

displayConditions: {
  conditions: [
    {
      label: 'Premium users',
      before: '{{#if isPremium}}',
      after: '{{/if}}',
    },
  ],
},

Mailchimp

displayConditions: {
  conditions: [
    {
      label: 'Subscribers in US',
      before: '*|IF:COUNTRY=US|*',
      after: '*|END:IF|*',
    },
  ],
},

Salesforce Marketing Cloud (AMPscript)

displayConditions: {
  conditions: [
    {
      label: 'Loyalty members',
      before: '%%[IF @loyaltyMember == "true" THEN]%%',
      after: '%%[ENDIF]%%',
    },
  ],
},

How Conditions Appear in Exported HTML

When a block has a display condition, the exported HTML wraps the block's content with the before and after strings:

{% if customer.vip %}
<mj-section>
  <mj-column>
    <mj-text>Exclusive VIP offer just for you!</mj-text>
  </mj-column>
</mj-section>
{% endif %}

Blocks without a display condition are exported normally without any wrapping.

Use Cases

• VIP content — Show exclusive offers or early access announcements only to premium customers
• Geographic targeting — Display region-specific promotions, shipping information, or legal disclaimers
• Plan-based features — Highlight upgrade CTAs for free users, or show advanced features for paid users
• A/B content — Show different content variants to different segments
• Seasonal campaigns — Show holiday-specific blocks to opted-in recipients
• Compliance — Include required legal text only for specific jurisdictions

Interaction with Merge Tags

Display conditions and merge tags work together naturally. Merge tags handle inline personalization (replacing variables within text), while display conditions handle block-level visibility (showing or hiding entire blocks).

You can use both in the same template — for example, a block wrapped in a display condition can also contain merge tags for personalization within that block's content.