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
#ifMatchesRegexStralong with regular expressionswhen you need to match against a pattern of characters. - Use
#ifEqwhen you need to check if two values are equal. - Use
#ifContainsStrwhen 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.
To display alternative content when the field doesn't match the pattern, use
the else block. The else block is optional.
# 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:
- Start with the exact value you expect.
- Add regex symbols only if the data has multiple potential formats to match against.
- 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:
Matching is case-sensitive.
Matching is against the full string by default.
To match part of a value, add
.*where needed.Regex modifiers at the end of a pattern are not supported (for example,
/i).-
Inverse-block syntax for
ifMatchesRegexStris not supported. Useelseor#unlessinstead.For example, the following syntax will not work:
# Regex quick reference
| Character | What it does | Example pattern | What it matches |
|---|---|---|---|
Period (.) | Matches any single character | man. |
many, mane
|
Star (*) | Matches the previous character/group zero or more times | yay* |
yay, yayyyy, ya
|
Plus (+) | Matches the previous character/group one or more times | loo+k |
look, loooook
|
Question mark (?) | Makes the previous character/group optional | colou?r |
color, colour
|
Parentheses (()) | Groups characters together | (ab)+ |
ab, abab, ababab
|
Square brackets ([]) | Matches one character from a set (learn more) | [Cc]alifornia |
California, california
|
Curly braces ({}) | Sets how many times something appears | A{2,4} |
AA, AAA, AAAA
|
Caret (^) | Anchors the match to the start of a string | ^gold |
gold, gold-tier
|
Dollar sign ($) | Anchors the match to the end of a string | gold$ |
gold, tier-gold
|
Pipe (|) | OR operator between alternatives (learn more) | yoga|cycling |
yoga or cycling
|
Backslash (\) | Escapes regex symbols so they are literal (learn more) | 1\+1 | 1+1 |
Wildcard (.*) | Matches any number of any characters (learn more) | .*yoga |
yoga, beginner-yoga, hot-yoga
|
# Wildcards
.* is a wildcard pattern that means "any number of any characters,"
including zero characters.
Examples:
-
.*yogamatches any string that ends withyoga.- Matches:
yoga,beginner-yoga,hot-yoga - Does not match:
yoga-mat,yoga-flow,cycling
- Matches:
-
yoga.*matches any string that starts withyoga.- Matches:
yoga,yoga-mat,yoga-flow - Does not match:
beginner-yoga,hot-yoga,cycling
- Matches:
-
.*yoga.*matches any string that containsyogaanywhere.- Matches:
yoga,yoga-mat,beginner-yoga,hot-yoga - Does not match:
cycling,running,strength
- Matches:
# 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|goldmatches eithersilverorgold. -
gold-(monthly|annual)groups alternatives that followgold-.
# 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 FitnessmatchesCarly Cardio | Fiterable Fitness. -
Still interested\?matchesStill interested?. -
CORP\\NorthAmericamatchesCORP\NorthAmerica. -
Loyalty\+matchesLoyalty+.
# 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)
# Display content based on a substring match
This pattern checks whether productName contains the substring "camera".
Regex pattern: .*camera.*
# 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
# 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-ESores-MX), it displays Spanish content. - If the locale is French (
fr-FRorfr-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
# 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
# Troubleshooting regular expressions in Handlebars
If your regular expression is not working as expected, here are some tips to help you troubleshoot:
- Preview with a real user profile and triggering event.
- Check case sensitivity in both field value and pattern.
- Confirm whether you need exact matching or partial matching (
.*). - Escape literal regex symbols with
\when needed. - If a message fails for only some users, check for null or missing fields in the user profile or triggering event.
- If you used inverse-block syntax with
ifMatchesRegexStr, note that this is not supported. Useelseor#unlessinstead.