In-app component reference

Updated August 21, 2024

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, 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).

Components

<x-base>
    <x-message>
        message content goes here
    </x-message>
    <x-watermark />
</x-base>
<script>
    // any custom JavaScript goes here
</script>

Raw HTML

<!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

Browser link

<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>

Deep Link

<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`

Copied to clipboard!

Latest features at Customer.io

Sending in-app messages just got easier

Pause and resume newsletters

Android 4.0 release

In-app component reference

How it works

Message composition

Components at a glance

Base

Box

Buttons: call to action (x-cta)

Open a link or deep-link

Perform a custom action

Close Button

Rows and columns

Row attributes

Column attributes

Headings

Horizontal rule

Image

List

Message

Paragraph

Spacer

Video

Latest features at Customer.io

Sending in-app messages just got easier

Pause and resume newsletters

Android 4.0 release

In-app component reference

How it works

Message composition

Components at a glance

Base

Box

Buttons: call to action (x-cta)

Open a link or deep-link

Perform a custom action

Close Button

Rows and columns

Row attributes

Column attributes

Headings

Horizontal rule

Image

List

Message

Paragraph

Spacer

Video

How can we make it better?