Flex Message layout

You can build complex Flex Messages layouts based on the specification for CSS Flexible Box (CSS Flexbox). The Flex box in the CSS Flexbox specification corresponds to the box component in a Flex Message, and the Flex items in the CSS Flexbox specification correspond to the components in a Flex Message.

This page explains how to adjust the overall layout, as well as the size and alignment of components (child elements) in a box. For more information about the JSON schema, see Image in the API reference.

Direction of placing components

You can decide the direction of placing child elements by deciding the direction of the main axis of the box. There are three layout types for placing child elements in a box.

The direction of placing child elements is specified by the layout property of the box.

Layout types
(Value of the layout property)
Description
horizontal The child elements are placed horizontally. The direction of placing the child elements is specified by the direction property of the bubble.
A box with this layout type is called a horizontal box.
vertical The child elements are placed vertically from top to bottom.
A box with this layout type is called a vertical box.
baseline The child elements are placed in the same way as in a horizontal box. For details on differences from a horizontal box, see Characteristics of the baseline box.
A box with this layout type is called a baseline box.

Available components

The components that can be used as child elements differ depending on the type of the box.

Horizontal box Vertical box Baseline box
Box
Button
Image
Icon
Text
Span (can be used as a child element of text)
Separator
Filler
Spacer (not recommended)

✅: Can be used as a child element of the box, ❌: Cannot be used as a child element of the box

Characteristics of the baseline box

A baseline box behaves in the same way as a horizontal box. However, its behavior is different from a horizontal box in terms of the following points.

Alignment in vertical direction

Alignment in the vertical direction is fixed at the baseline of the text. Texts with different font sizes are aligned at the baseline.

The baseline of an icon is the bottom of the icon image.

Baseline box

Unavailable properties

The following properties are unavailable in a baseline box:

  • gravity property
  • offsetBottom property (to be made available in future)

Width and height of components

The width or height of components for which the position property is set to relative is decided by the flex property of each component.

Width of components in a horizontal box

In a horizontal box, if the flex property of the components is set to 1 or higher, the free space is divided among the components on the basis of that value. For components in a horizontal box, the default value of the flex property is 1.

For example, if there are two components in a horizontal box, and the value of the flex property is 2 and 3, the free space (the width of the box in the following example) is divided at a ratio of two to three and assigned to each component.

flex property example 1

The Flex Message above can be created 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.",
        "wrap": true,
        "color": "#ff0000",
        "flex": 2
      },
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true,
        "color": "#0000ff",
        "flex": 3
      }
    ]
  }
}

If the value of the flex property is 0, the component's width will expand to the full size of its content. However, if the component's width exceeds the box's width, the part of the content that exceeds the box's width will not be displayed.

In the following sample, the box has three components whose flex property is 0, 2, and 3, respectively. The first component's flex property is 0, so a sufficient width is retained to display "Hello" included in the component. Then, the free space (in the following example, the part excluding the first component's width from the box's width) is divided at a ratio of two to three and assigned to the second and third components.

flex property example 2

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "text",
        "text": "Hello",
        "color": "#00ff00",
        "flex": 0
      },
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true,
        "color": "#ff0000",
        "flex": 2
      },
      {
        "type": "text",
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "wrap": true,
        "color": "#0000ff",
        "flex": 3
      }
    ]
  }
}
tip About the correspondence with the `flex` of the CSS Flexbox

The flex property of the component in the horizontal box corresponds to the flex of CSS Flexbox as follows.

  • When flex = 0: CSS Flexbox flex: 0 0 auto; equivalent layout

  • When flex = 0 or more: CSS Flexbox flex: X 0 0; equivalent layout (where X is the value of flex)

Height of components in a vertical box

In a vertical box, if the flex property of the components is set to 1 or a higher value, the free space is divided among the components on the basis of that value. For components in a vertical box, the default value of the flex property is 0.

In the Flex Message below, two vertical boxes are placed in the horizontal box. In addition, one text is placed in the vertical box on the left, and two texts and three separators are placed in the vertical box on the right.

flex property example 5

Each component is laid out according to the rules given below:

  1. Since the vertical box on the left has a height of five rows, the vertical box on the right also has the same height.
  2. The vertical box on the right has some free space that is not filled by two texts (one row each) and three separators alone.
  3. The free space is divided at a ratio of two to three on the basis of the flex property's value (2 and 3) of the two text, and is assigned to each component.

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "wrap": true,
            "text": "TEXT\nTEXT\nTEXT\nTEXT\nTEXT"
          }
        ],
        "backgroundColor": "#c0c0c0"
      },
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "separator",
            "color": "#ff0000"
          },
          {
            "type": "text",
            "text": "flex=2",
            "flex": 2
          },
          {
            "type": "separator",
            "color": "#ff0000"
          },
          {
            "type": "text",
            "text": "flex=3",
            "flex": 3
          },
          {
            "type": "separator",
            "color": "#ff0000"
          }
        ]
      }
    ]
  }
}
tip About the correspondence with the `flex` of the CSS Flexbox

The flex property of the component in the vertical box corresponds to the flex of CSS Flexbox as follows.

  • When flex = 0: CSS Flexbox flex: 0 0 auto; equivalent layout

  • When flex = 0 or more: CSS Flexbox flex: X 0 auto; equivalent layout (where X is the value of flex)

Width of a box

The width of a box can be specified by the width property. You can specify in % (the percentage with reference to the width of the parent element) or in pixels.

Note that if you specify the width property in a horizontal box or baseline box, the flex property is set to 0.

note When the `width` property is specified in pixels

A bubble's width depends on the size of the screen on which it is displayed. Specifying width in pixels to adjust the overall bubble layout may result in an unexpected layout depending on the device. Use the flex property to reduce the effect of screen size.

Height of a box

The height of a box can be specified by the height property. You can specify in % (the percentage with reference to the height of the parent element) or in pixels.

Note that if you specify the height property in a vertical box, the flex property is set to 0.

Size of other components

In components such as buttons and images, the size can be specified by a property different from the flex property. For more information about the JSON schema, see Image in the API reference.

Placement of components

If there is free space in the box, you can specify the horizontal and/or vertical alignment for each component.

Alignment in horizontal direction

The alignment style in the horizontal direction (cross-axis direction) of a vertical box can be specified by the align property. Specify one of the following values:

  • start: Left-aligned
  • end: Right-aligned
  • center: Center-aligned (default value)

align property example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "text",
        "text": "align=start",
        "align": "start"
      },
      {
        "type": "separator",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "align=center",
        "align": "center"
      },
      {
        "type": "separator",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "align=end",
        "align": "end"
      }
    ]
  }
}

Alignment in vertical direction

The alignment style in the vertical direction (cross-axis direction) of a horizontal box can be specified by the gravity property. Specify one of the following values:

  • top: Top-aligned (default value)
  • bottom: Bottom-aligned
  • center: Center-aligned
note Note

This property is ignored in a baseline box.

gravity property example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "wrap": true,
            "text": "TEXT\nTEXT\nTEXT\nTEXT\nTEXT"
          }
        ],
        "backgroundColor": "#c0c0c0"
      },
      {
        "type": "text",
        "text": "top",
        "gravity": "top"
      },
      {
        "type": "separator",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "center",
        "gravity": "center"
      },
      {
        "type": "separator",
        "color": "#ff0000"
      },
      {
        "type": "text",
        "text": "bottom",
        "gravity": "bottom"
      },
      {
        "type": "separator",
        "color": "#ff0000"
      }
    ]
  }
}

Box padding

The padding of the box is specified by the paddingAll, paddingTop, paddingBottom, paddingStart, and paddingEnd properties. The padding of the box expresses the size of the free space between the borderline of the box and the child element. You can specify a value in % (the percentage with reference to the width of the box), pixels, or any one of none, xs, sm, md, lg, xl, or xxl as the size. none does not set a space while the other values set a space whose size increases in the order of listing.

If you set paddingTop, paddingBottom, paddingStart, and paddingEnd in addition to paddingAll, the setting of paddingAll will be overwritten.

padding property example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "contents": [
      {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "hello, world"
          }
        ],
        "backgroundColor": "#ffffff"
      }
    ],
    "backgroundColor": "#ffd2d2",
    "paddingTop": "20px",
    "paddingAll": "80px",
    "paddingStart": "40px"
  }
}

If you change the text of the Flex Message above, the layout will become as shown below.

padding property example

spacing property of the box

The spacing property of the box (parent element) containing the component determines the minimum space between components. You can specify one of the following values: none, xs, sm, md, lg, xl, or xxl. none does not set a space while the other values set a space whose size increases in the order of listing.

In the Flex Message below, three vertical boxes are placed at equal intervals (md) in the horizontal box.

spacing property example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "spacing": "md",
    "contents": [
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT1"
          }
        ],
        "backgroundColor": "#80ffff"
      },
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT2"
          }
        ],
        "backgroundColor": "#80ffff"
      },
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT3"
          }
        ],
        "backgroundColor": "#80ffff"
      }
    ]
  }
}

To override this setting for a specific component, set the margin property of that component.

margin property of components

The margin property determines the minimum space from the previous component. You can specify one of the following values: none, xs, sm, md, lg, xl, or xxl. none does not set a space while the other values set a space whose size increases in the order of listing.

note Note

The margin property takes precedence over the spacing property of the parent box. The margin property of the component inserted at the top of the box is not reflected in the layout.

In the Flex Message below, three vertical boxes are placed in the horizontal box. The spacing property of the horizontal box is set to md, and the margin property of the third vertical box is set to xxl.

margin property example

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "horizontal",
    "spacing": "md",
    "contents": [
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT1"
          }
        ],
        "backgroundColor": "#80ffff"
      },
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT2"
          }
        ],
        "backgroundColor": "#80ffff"
      },
      {
        "type": "box",
        "layout": "vertical",
        "contents": [
          {
            "type": "text",
            "text": "TEXT3"
          }
        ],
        "backgroundColor": "#80ffff",
        "margin": "xxl"
      }
    ]
  }
}

Offset

The placement of the components can be adjusted even by specifying the property below:

  • position property

    The effect of the offset varies depending on the setting of the position property. You cannot specify absolute in the box immediately below the block.

  • offsetTop property, offsetBottom property, offsetStart property, and offsetEnd property

    You can specify a value in % (the percentage with reference to the size of the box), pixels, or any one of none, xs, sm, md, lg, xl, or xxl.

Here, in order to explain the effect of an offset, the setting of the horizontal box displayed as "TARGET" is changed with reference to the Flex Message below.

offset property example 1

The Flex Message above can be created by the JSON data below.

{
  "type": "bubble",
  "body": {
    "type": "box",
    "layout": "vertical",
    "contents": [
      {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "REFERENCE BOX\n1\n2\n3",
            "align": "center",
            "wrap": true
          }
        ],
        "backgroundColor": "#80ffff"
      },
      {
        "type": "box",
        "layout": "horizontal",
        "contents": [
          {
            "type": "text",
            "text": "TARGET"
          }
        ],
        "backgroundColor": "#ff8080"
      }
    ]
  }
}

When the position property has a value of relative

To perform alignment with reference to the regular position of components, set the position property to relative, and then specify the offset properties below. The position can be determined by a similar concept as Relative positioning of CSS Positioned Layout Module Level 3.

Property Description
offsetTop Specifies the amount moved to the top from the regular position
offsetBottom Specifies the amount moved to the bottom from the regular position
offsetStart Specifies the amount moved to the left from the regular position
offsetEnd Specifies the amount moved to the right from the regular position

Here, an example in which the setting of the horizontal box displayed as "TARGET" is changed as below will be introduced.

Property Value
position relative
offsetTop 10px
offsetBottom -
offsetStart 40px
offsetEnd -

The first bubble is before changing the setting, and the second bubble is after changing the setting.

offset property example 1 offset property example 2

When the position property has a value of absolute

To place the components with reference to the outer frame of the parent element, set the position property to absolute, and then specify the offset properties below. Layout can be performed by a method similar to that of Absolute positioning of CSS Positioned Layout Module Level 3.

Property Description
offsetTop Specifies the relative position from the upper end of the parent element to the upper end of the component.
offsetBottom Specifies the relative position from the lower end of the parent element to the lower end of the component.
offsetStart Specifies the relative position from the left end of the parent element to the left end of the component.
offsetEnd Specifies the relative position from the right end of the parent element to the right end of the component.
note Note

If the offset property is not specified, the position of the component may vary from screen to screen. We recommend explicitly specifying offsets both vertically (offsetTop or offsetBottom) and horizontally (offsetStart or offsetEnd).

The following example demonstrates how offsets work by showing the "TARGET" box in different positions.

Property Value
position absolute
offsetTop 10px
offsetBottom 20px
offsetStart 40px
offsetEnd 80px

The first bubble is before changing the setting, and the second bubble is after changing the setting.

offset property example 1 offset property example 3

About the size of the parent element and component

A box in which the position property is set to absolute does not affect the size of the parent element, and is also not affected by the parent element. Therefore, in the case of a component that is larger than the parent element, a part of the component is not displayed. If the component becomes larger due to the effect of the parent element (free space), it returns to its original size.

The next example shows a "REFERENCE BOX" in different positions.

Property Value
position absolute

The first bubble is before changing the setting, and the second bubble is after changing the setting.

offset property example 1 offset property example 4

The size of "REFERENCE BOX" does not affect the size of the parent element (vertical box), and is also not affected by the parent element. Therefore, portions larger than the parent element (rows "2" and "3") are not displayed. Moreover, the free space on the left and right that has become larger due to the effect of the parent element (free space) returns to its original size (width of the text "REFERENCE BOX").

About the order of rendering

Components are rendered in the order of JSON data. That is, the component written at the beginning of the JSON data is rendered right at the back, and the component written at the end is rendered right in the front of the bubble.

To change the order of rendered, change the order of components in the JSON data.

{{ $t("form.question.helpful") }}

{{ $t("form.question.detail") }}

{{ $t("form.question.improve") }}

{{ $t("form.info.start") }}{{ $t("form.info.link") }}{{ $t("form.info.end") }}


{{ $t("form.result.success") }}
{{ $t("form.result.error") }}
{{ $t("form.result.errorLink") }}