In-app component reference
UpdatedHow 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
, color
, and so on, 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="14px">
<!-- is the same as this -->
<x-paragraph style="font-size:14px;">
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!
Component | Code | Type | Description |
---|---|---|---|
Base | <x-base> | Layout | Required: The base component for your message. The base contains an x-message component. |
Box | <x-box> | Layout | A container for grouping and styling components |
Button (CTA) | <x-cta> | Button | A call to action button that also closes your message. |
Row and columns | <x-row> <x-column> | Layout | Creates a row containing up to 11 columns. |
Heading | <x-heading-1> — <x-heading-6> | Text | Headings for your message, like h1 - h6 |
Horizontal Rule | <x-hr> | Layout | A simple line to break up sections of a page |
Image | <x-image> | Media | An image in your message |
List | <x-list> | Text | An ordered or unordered list |
Message | <x-message> | Layout | Required: 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> | Text | A block of text |
Spacer | <x-spacer> | Layout | Adds space between components, independent of padding/margins. |
Video | <x-video> | Media | A 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.
Attribute | Type |
---|---|
title | string |
lang | string |
dir | enum One of: ltr , rtl , auto |
background | string |
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
text-align | enum One of: left , center , right |
class | string |
style | string |
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.
Attribute | Type |
---|---|
background | string |
width | string |
height | string |
padding | string |
margin | string |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
border-color | string |
box-shadow | string |
align | enum One of: left , center , right |
opacity | number |
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
text-align | enum One of: left , center , right |
lang | string |
dir | enum One of: ltr , rtl , auto |
label | string |
role | enum One of: article , region , navigation |
class | string |
style | string |
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.
Attribute | Type |
---|---|
background-color | string |
behavior | string , one of dismiss , openUrl , openDeepLink , performAction |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
border-color | string |
box-shadow | string |
width | string |
height | string |
padding | string |
margin | string |
align | enum One of: left , center , right |
color | string |
font-size | number |
font-family | string |
font-weight | string One of: 300 , 400 , 700 |
text-align | enum One of: left , center , right |
opacity | number |
hover-color | string |
hover-background-color | string |
hover-opacity | number |
hover-box-shadow | string |
hover-border-radius | string |
line-height | number |
text-transform | string One of: none , capitalize , uppercase , lowercase |
text-decoration | string One of: none , underline , line-through |
class | string |
style | string |
Open a link or deep-link
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.
Attribute | Required | Description |
---|---|---|
deep-link | if not href | string, the deep link you want to open |
href | if not deep-link | string, the URL you want to open |
new-tab | boolean, 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
Attribute | Type |
---|---|
layout | String containing array of numbers adding to 100, ex :layout='[50,50]' |
gap | number |
width | string |
padding | string |
margin | string |
align | enum One of: left , center , right |
background | string |
opacity | number |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
border-color | string |
box-shadow | string |
break-point | number |
fallback | enum One of: single , multi |
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
text-align | enum One of: left , center , right |
class | string |
style | string |
Column attributes
Attribute | Type |
---|---|
padding | string |
background | string |
opacity | number |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
border-color | string |
box-shadow | string |
class | string |
style | string |
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.
Attribute | Type |
---|---|
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
text-align | enum One of: left , center , right |
text-transform | string One of: none , capitalize , uppercase , lowercase |
text-decoration | string One of: none , underline , line-through |
margin | string |
lang | string |
dir | enum One of: ltr , rtl , auto |
class | string |
style | string |
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.
Attribute | Type |
---|---|
background-color | string |
height | number |
width | string |
align | enum , One of: left , center , right |
margin | string |
class | string |
style | string |
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.
Attribute | Type |
---|---|
src | string |
href | string |
alt | string |
width | string |
margin | string |
align | enum One of: left , center , right |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
border-color | string |
box-shadow | string |
opacity | number |
hover-opacity | number |
hover-box-shadow | string |
hover-border-radius | string |
background-color | string |
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
letter-spacing | number |
line-height | number |
text-align | enum One of: left , center , right |
text-transform | string One of: none , capitalize , uppercase , lowercase |
text-decoration | string One of: none , underline , line-through |
class | string |
style | string |
srcset | string |
sizes | string |
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).
Attribute | Type |
---|---|
color | string |
element | enum One of: ul , ol (defaults to ul ) |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
list-style-type | enum One of: none , disc , circle , square , decimal , decimal-leading-zero , lower-roman , upper-roman , lower-alpha , upper-alpha |
text-align | enum One of: left , center , right |
text-transform | string One of: none , capitalize , uppercase , lowercase |
text-decoration | string One of: none , underline , line-through |
class | string |
style | string |
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.
Attribute | Type |
---|---|
background | string |
border-color | string |
border-radius | string |
border-style | string |
border-width | string |
box-shadow | string |
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
margin | string |
padding | string |
text-align | enum One of: left , center , right |
width | string |
lang | string |
dir | enum One of: ltr , rtl , auto |
class | string |
style | string |
Paragraph
The x-paragraph
is basically a <p>
tag in HTML in that’s it’s a block-level component that contains text.
Attribute | Type |
---|---|
color | string |
font-family | string |
font-size | number |
font-weight | string One of: 300 , 400 , 700 |
line-height | number |
text-align | enum One of: left , center , right |
text-transform | string One of: none , capitalize , uppercase , lowercase |
text-decoration | string One of: none , underline , line-through |
margin | string |
lang | string |
dir | enum One of: ltr , rtl , auto |
class | string |
style | string |
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.
Attribute | Type |
---|---|
size | number |
class | string |
style | string |
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).
Attribute | Type |
---|---|
src | string |
alt | string |
margin | string |
width | string |
align | enum One of: left , center , right |
border-color | string |
border-radius | string |
border-style | enum One of: none , solid , dashed , dotted |
border-width | string |
box-shadow | string |
opacity | number |
class | string |
style | string |