Flex Message elements

This page explains Flex Message elements through example.

Here are the types of Flex Message elements:

Container

A container is the top-level structure of a Flex Message. Here are the types of containers available.

Bubble

A bubble is a container that contains one message bubble.

Bubble example

For more information about the JSON schema of the bubble container, see Bubble container in the API reference.

Setting text directionality

Set text directionality and the order of components in horizontal boxes with the direction property of the bubble container.

Value of the direction property Placement direction of components String direction
ltr Left to right Left-to-right horizontal writing
rtl Right to left Right-to-left horizontal writing

A carousel is a container that contains multiple bubbles as child elements. The bubbles in the carousel will be shown in order by scrolling horizontally.

If any of the bubbles in the carousel container has a body block, the body block extends so that the bubble has the same height as the highest bubble in the carousel container.

Carousel example

The Flex Message above is composed by the JSON data below.

{
  "type": "carousel",
  "contents": [
    {
      "type": "bubble",
      "body": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "wrap": true
          }
        ]
      },
      "footer": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "button",
            "style": "primary",
            "action": {
              "type": "uri",
              "label": "Go",
              "uri": "https://example.com"
            }
          }
        ]
      }
    },
    {
      "type": "bubble",
      "body": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "Hello, World!",
            "wrap": true
          }
        ]
      },
      "footer": {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "button",
            "style": "primary",
            "action": {
              "type": "uri",
              "label": "Go",
              "uri": "https://example.com"
            }
          }
        ]
      }
    }
  ]
}

For more information about the JSON schema of the carousel container, see Carousel container in the API reference.

Block

Blocks make up a bubble container. Here are the types of blocks available.

Type Description
Header Block that displays the message subject or header. Include a box component in this block.
Hero Block that displays main image content. Include an image component in this block.
Body Block that displays main message content. Include a box component in this block.
Footer Block that displays buttons and supplementary information. Include a box component in this block.

Each type of block can be specified only once in a bubble container and can be also omitted. Blocks are displayed in the order of header, hero, body and footer.

Block example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "header": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "header"
      }
    ]
  },
  "hero": {
    "type": "image",
    "url": "https://example.com/flex/images/image.jpg",
    "size": "full",
    "aspectRatio": "2:1"
  },
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "body"
      }
    ]
  },
  "footer": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "footer"
      }
    ]
  }
}

For more information about the JSON schema of the block, see Bubble container in the API reference.

Objects for the block style

You can customize the style of each block with the styles property of the bubble container.

You can change whether to display a separator between blocks and the background color of the block.

Block style example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "styles": {
    "header": {
      "backgroundColor": "#ffaaaa"
    },
    "body": {
      "backgroundColor": "#aaffaa"
    },
    "footer": {
      "backgroundColor": "#aaaaff"
    }
  },
  "header": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "header"
      }
    ]
  },
  "hero": {
    "type": "image",
    "url": "https://example.com/flex/images/image.jpg",
    "size": "full",
    "aspectRatio": "2:1"
  },
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "body"
      }
    ]
  },
  "footer": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "footer"
      }
    ]
  }
}

For more information about the styles property, see Bubble container in the API reference.

Component

Components make up a Flex Message block. Here are the types of components available:

Box

This component defines the message layout and can contain other components including a box as child elements.

The child elements are placed according to the method specified by the properties of the box component. For more information about placing child elements, see Flex Message layout.

Button

This component draws a button.

When the user taps a button, an action is performed. For more information about available actions, see Actions.

There are three styles for the button component and you can change the color of the button with any of the styles.

Button example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "spacing": "md",
    "contents": [
      {
        "type": "button",
        "style": "primary",
        "action": {
          "type": "uri",
          "label": "Primary style button",
          "uri": "https://example.com"
        }
      },
      {
        "type": "button",
        "style": "secondary",
        "action": {
          "type": "uri",
          "label": "Secondary style button",
          "uri": "https://example.com"
        }
      },
      {
        "type": "button",
        "style": "link",
        "action": {
          "type": "uri",
          "label": "Link style button",
          "uri": "https://example.com"
        }
      }
    ]
  }
}

For more information about the JSON schema of the button component, see Button component in the API reference.

Filler

This is an invisible component to adjust the position of components within a box.

You can put a space between, before, or after components by inserting a filler anywhere within a box.

The filler's flex property is fixed to 1. With this property, you can adjust the relative width or height of a space.

The example below uses a filler to create a space between the images.

Filler example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg"
      },
      {
        "type": "filler"
      },
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg"
      }
    ]
  }
}

For more information about the JSON schema of the filler component, see Filler component in the API reference.

Icon

This component draws an icon that decorates the adjacent text.

This component can be used only in a baseline box.

Icon example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "md"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "md"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "lg"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "lg"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "xl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "xl"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "xxl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "xxl"
          }
        ]
      },
      {
        "type": "box",
        "layout": "baseline",
        "contents": [
          {
            "type": "icon",
            "url": "https://example.com/flex/images/icon.png",
            "size": "3xl"
          },
          {
            "type": "text",
            "text": "The quick brown fox jumps over the lazy dog",
            "size": "3xl"
          }
        ]
      }
    ]
  }
}

For more information about the JSON schema of the icon component, see Icon component in the API reference.

Image

This component draws an image. You can specify a JPEG or PNG image.

Image example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "image",
        "url": "https://example.com/flex/images/image.jpg",
        "size": "md"
      }
    ]
  }
}

For more information about the JSON schema of the image component, see Image component in the API reference.

Specifying the image size

Aspect ratio

Specify the max width of the image with the size property and the aspect ratio (horizontal to vertical ratio) of the image with the aspectRatio property. The rectangular area determined by the size and aspectRatio properties is called a drawing area.

If the aspect ratio of the image and that specified by the aspectRatio property do not match, the image is scaled according to the aspectMode property. See "Styles for sizing the image" below.

Styles for sizing the image

The aspectMode property specifies the sizing style of the image.

  • aspectMode=cover: The image fills the entire drawing area. Parts of the image that do not fit in the drawing area are not displayed.
  • aspectMode=fit: The entire image is displayed in the drawing area. The background is displayed in the unused areas to the left and right of vertical images and in the areas above and below horizontal images.
Width of the image and the image component

If the image width specified by the size property is larger than that calculated from the flex property, the width of the drawing area is scaled down to the width of the component.

Separator

This component draws a separator within a box. A vertical line will be drawn in a horizontal box and a horizontal line will be drawn in a vertical box.

Separator example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "spacing": "md",
    "contents": [
      {
        "type": "box",
        "layout": "horizontal",
        "spacing": "md",
        "contents": [
          {
            "type": "text",
            "text": "orange"
          },
          {
            "type": "separator"
          },
          {
            "type": "text",
            "text": "apple"
          }
        ]
      },
      {
        "type": "separator"
      },
      {
        "type": "box",
        "layout": "horizontal",
        "spacing": "md",
        "contents": [
          {
            "type": "text",
            "text": "grape"
          },
          {
            "type": "separator"
          },
          {
            "type": "text",
            "text": "lemon"
          }
        ]
      }
    ]
  }
}

For more information about the JSON schema of the separator component, see Separator component in the API reference.

Spacer

This is an invisible component that places a fixed-size space at the beginning or end of the box. This component is used to expand a space at the beginning or end of a block.

Tip: Use the spacing and margin properties to adjust spaces between components. For more information, see Spaces between components.

The example below uses a spacer component to expand the space between the body block and footer block.

Spacer example

The Flex Message above is composed by the JSON data below.

{
 "type": "bubble",
 "body": {
   "type": "box",
   "layout": "vertical",
   "contents": [
     {
       "type": "image",
       "url": "https://example.com/flex/images/image.jpg",
       "size": "full"
     }
   ]
 },
 "footer": {
   "type": "box",
   "layout": "vertical",
   "contents": [
     {
       "type": "spacer",
       "size": "xl"
     },
     {
       "type": "button",
       "action": {
         "type": "uri",
         "label": "Tap me",
         "uri": "https://example.com"
       },
       "style": "primary",
       "color": "#0000ff"
     }
   ]
 }
}

For more information about the JSON schema of the spacer component, see Spacer component in the API reference.

Text

This component draws a text string. You can specify the color, size, and width of the font.

Text example

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "md",
        "align": "center",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "lg",
        "align": "center",
        "color": "#00ff00"
      },
      {
        "type": "text",
        "text": "Closing the distance",
        "size": "xl",
        "align": "center",
        "weight": "bold",
        "color": "#0000ff"
      }
    ]
  }
}

For more information about the JSON schema of the text component, see Text component in the API reference.

Wrapping text

By default, text overflowing beyond the width of the text component is replaced by an ellipsis.

Example without text wrap

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }
    ]
  }
}

You can wrap text within the text component by setting the wrap property to true. Also, you can use a new line character (\n) to begin on a new line.

Example with text wrap

The Flex Message above is composed by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\n tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true
      }
    ]
  }
}