Handlebars Reference: Regular Expressions

Use #ifMatchesRegexStr to display content when a string field matches a regex pattern.

If regex is new to you, start simple. Build your pattern in small steps, test in template preview, then add complexity only if you need it.

# In this article

# When to use regular expressions in Handlebars

Not sure when to use regular expressions in Handlebars? Here are some guidelines:

• Use #ifMatchesRegexStr along with regular expressionswhen you need to match against a pattern of characters.
• Use #ifEq when you need to check if two values are equal.
• Use #ifContainsStr when you need to check if a string contains a substring.

# #ifMatchesRegexStr helper syntax

When you use #ifMatchesRegexStr in a Handlebars expression, Iterable evaluates a regex pattern against the value specified. If the pattern matches, the helper displays the block's content. If the pattern does not match, the helper either displays nothing or, if an else statement is included, displays the provided alternative fallback content.

For examples, see Common use cases below.

# Properties

• fieldName — User profile or triggering event field to evaluate.
• pattern — Regex pattern used for matching.
• content — Content shown when the field matches the pattern.
• else content (optional) — Content shown when there is no match.

# Format

When used without fallback content, the helper displays nothing if the field doesn't match the pattern.

{{#ifMatchesRegexStr fieldName "pattern"}}
  <div>content when matched</div>
{{/ifMatchesRegexStr}}

To display alternative content when the field doesn't match the pattern, use the else block. The else block is optional.

{{#ifMatchesRegexStr fieldName "pattern"}}
  <div>Content that displays when the field value matches the pattern</div>
{{else}}
  <div>Fallback content that displays when the field value does not match the pattern</div>
{{/ifMatchesRegexStr}}

# Creating a regex pattern

You can use regular expressions in Iterable in the following ways:

• In Handlebars helpers, such as #ifMatchesRegexStr.
• In journey Attribute Split tiles.

For examples of how to use regular expressions in Iterable, see the Common use cases below.

Use this workflow to build your regex pattern:

1. Start with the exact value you expect.
2. Add regex symbols only if the data has multiple potential formats to match against.
3. Test the pattern in template preview.

For more help, try https://regex101.com or another third-party regex tester to build and validate patterns.

Regardless of how you create your regex pattern, always test it in template preview before sending.

# Iterable-specific regex behavior and limitations

These rules are specific to how Iterable evaluates regex:

# Regex quick reference

# Wildcards

.* is a wildcard pattern that means "any number of any characters," including zero characters.

Examples:

• .*yoga matches any string that ends with yoga.
  • Matches: yoga, beginner-yoga, hot-yoga
  • Does not match: yoga-mat, yoga-flow, cycling
• yoga.* matches any string that starts with yoga.
  • Matches: yoga, yoga-mat, yoga-flow
  • Does not match: beginner-yoga, hot-yoga, cycling
• .*yoga.* matches any string that contains yoga anywhere.
  • Matches: yoga, yoga-mat, beginner-yoga, hot-yoga
  • Does not match: cycling, running, strength

# Character sets

Use inside square brackets with operators to define a character set:

• Caret (^) defines a character set to match characters outside of the set ("not" operator).
• Hyphen (-) defines a range to match characters within the set.

Examples:

• [0-9] matches any digit (0-9).
• [A-Z] matches any uppercase letter (A-Z).
• [^0-9] matches any character that is not a digit (anything except 0-9).

# OR operator

With the OR operator (|), you do not need to wrap alternatives in parentheses unless you are grouping part of a larger pattern.

Examples:

• silver|gold matches either silver or gold.
• gold-(monthly|annual) groups alternatives that follow gold-.

# Escaping regex symbols

Use \ to match regex symbols literally:

• \| matches a literal pipe.
• \? matches a literal question mark.
• \\ matches a literal backslash.
• \+ matches a literal plus sign.

Examples:

• .+ \| Fiterable Fitness matches Carly Cardio | Fiterable Fitness.
• Still interested\? matches Still interested?.
• CORP\\NorthAmerica matches CORP\NorthAmerica.
• Loyalty\+ matches Loyalty+.

# Common use cases for regular expressions in Handlebars

These are some common use cases for regular expressions in Handlebars.

# Display content based on a regex pattern match

This example checks whether membershipTier follows the pattern gold-monthly or gold-annual.

Regex pattern: gold-(monthly|annual)

{{#ifMatchesRegexStr membershipTier "gold-(monthly|annual)"}}
  <div>Thanks for being a Gold member!</div>
{{/ifMatchesRegexStr}}

# Display content based on a substring match

This pattern checks whether productName contains the substring "camera".

Regex pattern: .*camera.*

{{#ifMatchesRegexStr productName ".*camera.*"}}
  <div>Recommended accessories for your camera</div>
{{/ifMatchesRegexStr}}

# Display content based on a multiple value match

This pattern checks whether country is one of the following values:

• United States
• Canada
• Australia

Regex pattern: United States|Canada|Australia

{{#ifMatchesRegexStr country "United States|Canada|Australia"}}
  <div>Choose your mega deal</div>
{{/ifMatchesRegexStr}}

# Display content based on a locale match with fallback

This example has two pattern checks for locale and displays the appropriate content based on the user's language:

• If the locale is Spanish (es-ES or es-MX), it displays Spanish content.
• If the locale is French (fr-FR or fr-CA), it displays French content.
• If the locale is not one of those values, it displays English fallback content.

This use case helps create snippets of content that can be reused in templates that have many locales.

Regex pattern: es-ES|es-MX|fr-FR|fr-CA

{{#ifMatchesRegexStr locale "es-ES|es-MX"}}
  <div>Buenas noticias: el artículo que viste todavía está disponible.</div>
{{else ifMatchesRegexStr locale "fr-FR|fr-CA"}}
  <div>Bonne nouvelle : l’article que vous avez consulté est toujours disponible.</div>
{{else}}
  <div>Good news: the item you viewed is still available.</div>
{{/ifMatchesRegexStr}}

# Display content based on a date suffix match (st, nd, rd, th)

This pattern checks the value for dateDay and displays the appropriate suffix for the day.

• If the day is 1, 21, or 31, it displays the suffix "st". Example: "1st", "21st", "31st"
• If the day is 2, 22, it displays the suffix "nd". Example: "2nd", "22nd"
• If the day is 3, 23, it displays the suffix "rd". Example: "3rd", "23rd"
• If the day is any other number, it displays the suffix "th". Example: "4th", "18th", "30th", etc.

Regex pattern: 01|21|31

{{#assign "dateDay"}}{{dateMath "now" "+7d" format="dd"}}{{/assign}}
{{#ifMatchesRegexStr dateDay "01|21|31"}}{{dateDay}}st
{{else ifMatchesRegexStr dateDay "02|22"}}{{dateDay}}nd
{{else ifMatchesRegexStr dateDay "03|23"}}{{dateDay}}rd
{{else}}{{dateDay}}th
{{/ifMatchesRegexStr}}

# Troubleshooting regular expressions in Handlebars

If your regular expression is not working as expected, here are some tips to help you troubleshoot:

# Related references

• Handlebars Overview
• Handlebars Reference: Conditional Logic Helpers
• Handlebars Reference: Text Helpers