In-app component reference

Updated

How it works

In-app messages use an HTML-like syntax with components similar to HTML elements beginning with x-.

In HTML, you typically pass CSS styles to components in a style attribute. You can still do that with our in-app code editor, but each component also exposes a number of top-level attributes that makes it easy to set things like fonts, colors, and so on. These attributes correspond to common CSS properties, like font-size and color, so all the styles should make sense to you if you’re familiar with CSS.

For example, in our paragraph component, you can set the font-size attribute to change the size of the text or you can set style="font-size...". They’re functionally the same!

<!-- this -->
<x-paragraph :font-size="14" color="red">

<!-- is the same as this -->
<x-paragraph style="font-size:14px;color:red">

 Format top-level attributes that take number or boolean values like :attribute-name

See the component above: color="red" contains a string value, but :font-size="14" is an integer so it starts with a colon.

Message composition

While you can typically mix and match components in your message, there is a basic structure that most messages should follow.

Messages need a base component, x-base, that sets the overall style of your message. Inside the base, you’ll typically have a x-message component that frames your message and sets the background color.

If you want to write your message in HTML, we’ve provided a base structure below as well. You should use this structure to avoid unexpected interactions in your message (like zooming, scrolling, and so on).

<x-base>
    <x-message>
        message content goes here
    </x-message>
    <x-watermark />
</x-base>
<script>
    // any custom JavaScript goes here
</script>
<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" />
        <title>Message Title</title>
        <style></style>
    </head>
    <body>
        message content goes here
    </body>
</html>

Components at a glance

In-app messages use extended HTML components—described in detail on this page—to support our drag-and-drop editor. You can use standard HTML elements, but you won’t be able to drag them or manipulate them in our editor!

ComponentCodeTypeDescription
Base<x-base>LayoutRequired: The base component for your message. The base contains an x-message component.
Box<x-box>LayoutA container for grouping and styling components
Button (CTA)<x-cta>ButtonA call to action button that also closes your message.
Row and columns<x-row>
<x-column>
LayoutCreates a row containing up to 11 columns.
Heading<x-heading-1><x-heading-6>TextHeadings for your message, like h1 - h6
Horizontal Rule<x-hr>LayoutA simple line to break up sections of a page
Image<x-image>MediaAn image in your message
List<x-list>TextAn ordered or unordered list
Message<x-message>LayoutRequired: The frame of your message, containing all the other child components of your message. This component controls the background color and set padding between your message and where it appears in your app—including a box shadow.
Paragraph<x-paragraph>TextA block of text
Spacer<x-spacer>LayoutAdds space between components, independent of padding/margins.
Video<x-video>MediaA video in your message

Base

The x-base component is the equivalent of a blank page. Apply any basic settings, like fonts and colors, for the message here. Your message will inherit all text styles set on the x-base component. This is the first component in your message, and you should only use it once, wrapping all other components inside it.

AttributeType
titlestring
langstring
direnum
One of: ltr, rtl, auto
backgroundstring
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
text-alignenum
One of: left, center, right
classstring
stylestring

Box

Use the <x-box> component to group and style components that should, for instance, stand out from the rest of the content, like a footer or an offer. It’s similar to an HTML section. All components inside the x-box component will inherit its text styles.

You can also use x-box to add semantic meaning to a group of components by using the role and label settings. Adding accessibility in this way is an advanced feature; only use this if you understand the impact as this can be negative when used incorrectly.

AttributeType
backgroundstring
widthstring
heightstring
paddingstring
marginstring
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
border-colorstring
box-shadowstring
alignenum
One of: left, center, right
opacitynumber
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
text-alignenum
One of: left, center, right
langstring
direnum
One of: ltr, rtl, auto
labelstring
roleenum
One of: article, region, navigation
classstring
stylestring

Buttons: call to action (x-cta)

Buttons in in-app messages are called x-cta, short for call to action. When someone clicks or taps a button, it’ll perform a behavior: dismiss, openUrl, performAction. All behaviors dismiss the message, but the openUrl, and performAction behaviors expose extra fields determining what happens when someone uses the button. For example, the openUrl action includes an href or deep-link attribute for the link you want to open.

If you don’t want to perform an action or track clicks on a button, you can add a close button to your message.

AttributeType
background-colorstring
behaviorstring, one of dismiss, openUrl, openDeepLink, performAction
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
border-colorstring
box-shadowstring
widthstring
heightstring
paddingstring
marginstring
alignenum
One of: left, center, right
colorstring
font-sizenumber
font-familystring
font-weightstring
One of: 300, 400, 700
text-alignenum
One of: left, center, right
opacitynumber
hover-colorstring
hover-background-colorstring
hover-opacitynumber
hover-box-shadowstring
hover-border-radiusstring
line-heightnumber
text-transformstring
One of: none, capitalize, uppercase, lowercase
text-decorationstring
One of: none, underline, line-through
classstring
stylestring

The openUrl behavior takes a person to a browser URL or a deep link. When you set behavior to openUrl, you’ll set an href or deep-link determining what URL to open and new-tab determining if the URL opens in a new tab or not.

openURL doesn’t automatically dismiss a message. We’re working to add this option to the editor in the future. In the meantime, you can manually configure buttons to close the message after opening a link.

AttributeRequiredDescription
deep-linkif not hrefstring, the deep link you want to open
hrefif not deep-linkstring, the URL you want to open
new-tabboolean, if true, the link opens in a new tab
<x-cta 
    behavior="openUrl" 
    href="https://example.com/sfgiants" 
    :new-tab="true" 
    border-radius="8px" 
    font-family="Helvetica" 
    font-weight="700" 
    :full-width="true" 
    tracked-response-name="2" 
    hover-background-color="#0046a0" 
    background-color="#0057c4" 
    padding="24px 0px"
    >
    CTA button
</x-cta>
<x-cta 
    behavior="openUrl" 
    deep-link="my-app://sfgiants" 
    :new-tab="true" 
    border-radius="8px" 
    font-family="Helvetica" 
    font-weight="700" 
    :full-width="true" 
    tracked-response-name="1" 
    hover-background-color="#0046a0" 
    background-color="#0057c4" 
    padding="24px 0px"
    >
    CTA Button
</x-cta>

Perform a custom action

A custom action is a behavior that you’ve programmed in your app. When someone interacts with your message, it’ll call this custom behavior. For example, if your call to action is to change a setting, you might set a custom action to enable the setting.

However, to perform custom actions, you must have added a function using the action name and listen for that function name. Otherwise, the button will dismiss your message and nothing will happen.

<x-cta 
    behavior="performAction" 
    action="myCustomAction" 
    border-radius="8px" 
    font-family="Helvetica" 
    font-weight="700" 
    :full-width="true" 
    tracked-response-name="3" 
    hover-background-color="#0046a0" 
    background-color="#0057c4" 
    padding="24px 0px"
    >
    CTA Custom Action Button
</x-cta>

Close Button

The close button is actually an x-image component with a close icon. It’s used to dismiss an in-app message without taking any action. Most actions also automatically close your message, so you don’t need to include a close button in your message. The only button that doesn’t automatically close your message is the Custom Action.

Rows and columns

A row contains a group of column elements. It helps add structure to your layout—like cells in a table, columns in a grid, or components in a flexbox. The most common use case for rows and columns are buttons. When you drag a group of buttons into your layout, it’s actually an x-row component that contains a series of x-column components and a button in each column.

Don’t use x-row to create a single column layout. If you just want to separate a single element or column from the rest of your layout, use x-box instead.

It’s important that the number of columns you define in the layout property of your x-row matches the number of x-column components you add to your layout. For example, if you set your row’s column count to four, then your code needs to reflect your columns in the format :layout="[25,25,25,25]". In this case, each column is 25% of the row’s width.

The default behavior of columns is to scale down to a narrower layout. If you want columns to stack on smaller viewports, you can set the break-point property to the screen size when you want columns to stack.

 Use buttons to start a row of columns

The x-row and x-column elements can be hard to set up manually. When you want to set up columns, you can drag a row of buttons into your layout. This’ll start you off with a row, columns, and all the properties you need for both—so you don’t have to start from scratch!

Row attributes

AttributeType
layoutString containing array of numbers adding to 100, ex :layout='[50,50]'
gapnumber
widthstring
paddingstring
marginstring
alignenum
One of: left, center, right
backgroundstring
opacitynumber
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
border-colorstring
box-shadowstring
break-pointnumber
fallbackenum
One of: single, multi
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
text-alignenum
One of: left, center, right
classstring
stylestring

Column attributes

AttributeType
paddingstring
backgroundstring
opacitynumber
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
border-colorstring
box-shadowstring
classstring
stylestring

Headings

There are six heading components, x-heading-1 to x-heading-6, representing the six levels of HTML headings h1 to h6. All headings support the same attributes; they simply have different default styles.

AttributeType
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
text-alignenum
One of: left, center, right
text-transformstring
One of: none, capitalize, uppercase, lowercase
text-decorationstring
One of: none, underline, line-through
marginstring
langstring
direnum
One of: ltr, rtl, auto
classstring
stylestring

Horizontal rule

Use the x-hr component to separate content with a horizontal rule. It creates a simple line that can visually break up sections of a page.

AttributeType
background-colorstring
heightnumber
widthstring
alignenum, One of: left, center, right
marginstring
classstring
stylestring

Image

The x-image component adds an image to your message. When you choose a file, you can either select from assets you’ve already uploaded or upload an image.

AttributeType
srcstring
hrefstring
altstring
widthstring
marginstring
alignenum
One of: left, center, right
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
border-colorstring
box-shadowstring
opacitynumber
hover-opacitynumber
hover-box-shadowstring
hover-border-radiusstring
background-colorstring
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
letter-spacingnumber
line-heightnumber
text-alignenum
One of: left, center, right
text-transformstring
One of: none, capitalize, uppercase, lowercase
text-decorationstring
One of: none, underline, line-through
classstring
stylestring
srcsetstring
sizesstring

List

The x-list component adds an ordered or unordered list to your message. It’s similar to an HTML ul or ol elements. Use the list-style to determine the list decorators (bullets, circles, roman numerals, etc).

AttributeType
colorstring
elementenum
One of: ul, ol (defaults to ul)
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
list-style-typeenum
One of: none, disc, circle, square, decimal, decimal-leading-zero, lower-roman, upper-roman, lower-alpha, upper-alpha
text-alignenum
One of: left, center, right
text-transformstring
One of: none, capitalize, uppercase, lowercase
text-decorationstring
One of: none, underline, line-through
classstring
stylestring

Message

The x-message component is the background of your message. Where the x-base contains items like your message’s fonts and other base styles, the message provides a background color and is where you’ll set padding between your message and where it appears in your app.

It’s also common to apply a box-shadow to this component to make it appear like it’s floating above your app.

AttributeType
backgroundstring
border-colorstring
border-radiusstring
border-stylestring
border-widthstring
box-shadowstring
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
marginstring
paddingstring
text-alignenum
One of: left, center, right
widthstring
langstring
direnum
One of: ltr, rtl, auto
classstring
stylestring

Paragraph

The x-paragraph is basically a <p> tag in HTML in that’s it’s a block-level component that contains text.

AttributeType
colorstring
font-familystring
font-sizenumber
font-weightstring
One of: 300, 400, 700
line-heightnumber
text-alignenum
One of: left, center, right
text-transformstring
One of: none, capitalize, uppercase, lowercase
text-decorationstring
One of: none, underline, line-through
marginstring
langstring
direnum
One of: ltr, rtl, auto
classstring
stylestring

Spacer

We recommend you use margin or padding properties where possible to add space between components. However, if for any reason those properties don’t fulfill your needs, you can use the x-spacer component. The x-spacer component allows for either vertical or horizontal spacing.

AttributeType
sizenumber
classstring
stylestring

Video

The x-video component adds an externally-hosted video to your message. You’ll provide the URL to your video. We support videos from Vimeo, Loom, Youtube, and Wistia.

If you use an unsupported platform, we’ll show a black preview and link to the video.

There aren’t any particular constraints on video size or dimensions, but you’ll see the best results when you use a video that’s optimized for your audience’s medium. For example, if you send your message to mobile devices, you might want to use a smaller or shorter videos so it better fits your mobile audience’s needs and plays well whether they’re on cellular or WiFi connections.

 We don’t support YouTube shorts

You can’t link to a video with /shorts in the path. You’ll need to link to a standard, full-length video (that typically contains /watch in the URL).

AttributeType
srcstring
altstring
marginstring
widthstring
alignenum
One of: left, center, right
border-colorstring
border-radiusstring
border-styleenum
One of: none, solid, dashed, dotted
border-widthstring
box-shadowstring
opacitynumber
classstring
stylestring
Copied to clipboard!
  Contents
Is this page helpful?