Bixby Developer Center

Guides

Layout Components

In Creating Bixby Views, we've seen how layouts are built from smaller components: cards, cells, and various text objects like titles and paragraphs. Let's go into more detail about layout components and their containers.

Note

Input views can use layouts, layout macros, and layout components in certain places. However, input views have their own distinct set of components. For a discussion of input components, read the Input Views section, which links to further documentation on individual components.

Components are placed within a content block under layout. A content block consists of one or more section blocks.

Each section block can itself have just two child keys:

  • title: The title that will be displayed for the section. Unlike titles within other components, this title cannot be styled (although it can be a template). This is optional, and only one is allowed for a content block.
  • content: The actual components within this section.

A layout block has only one content block as a direct child; that content block can have multiple section blocks that each have one content block. So a layout with multiple sections would look like this:

layout {
// the match directive for the overall layout
match: Object (variable)

content {
section {
content {
// content for first section
}
}
section {
content {
// content for second section
}
}
}
}

The content block within a section contains one or more view components, which are divided into the following types:

Note

Be aware of which components you are adding to your layouts and layout macros, because different components are available under different views. If you call a layout or layout macro in a view and that layout specifies a component that the view does not support, Bixby Developer Studio will throw an error. Similarly, you should consider which layout macros are being called within a layout itself. The same layout macro invoked in one component might not be valid if used within a different component, as the list of supported child components could differ.

You can read the Designing with Bixby Views design guide and the Building Views (UI) developer guide to check if your layout is using the correct components for that moment and that view.

Areas

  • title-area: a container for titles and subtitles. A title-area has three slots that can contain either a text or a single-line component.
  • cell-area: An area that contains a cell, which displays information for a single subject. This has three child keys for slots (slot1, slot2, and slot3); see the discussion of slots below.

Text

  • paragraph: a paragraph of styled text.
  • single-line: a single line of text that can contain styled text, spacers, and images. A single-line block may have one or more text, image, and spacer keys within it; when it is rendered, they are concatenated into a single display line.
  • text is an interior container for styled text (see below) that can only appear inside other elements such as single-line.

The paragraph and single-line blocks seem similar, but they have different use cases. A paragraph is a single unit of styled text that can be one or more lines, with wrapping left up to the display device. A single-line always displays as a single line of text, but can include spacers and inline images, letting you build a more complicated line of data. Note that if a single-line component generates more text that can be displayed on the device's screen in one line, it will be truncated with an ellipsis ("…").

Styled text blocks such as paragraph and text have two keys:

Cards

A card is a representation of a single subject or result: for example, a hotel room being booked, or a calendar event. Cards should always have title text, and usually have detail text (for example, a description of the hotel room). In addition, they might have image backgrounds, solid color backgrounds, image thumbnails, and even maps with pins. Cards all can have title-area components, and in addition, all cards can have on-click blocks that let you provide an intent to be executed when the card's label is clicked or tapped.

  • title-card: a container that in turn contains a title-area.
  • cell-card: This cell/card hybrid is styled like a cell, and has the same three child keys for slots (slot1, slot2, and slot3) that cell-area does. But, like other cards, it has an on-click block.
  • image-card: similar to title-card, but with an image-url to let you specify a background image for the card.
  • thumbnail-card: treats the image as a thumbnail that can be given a position on the card rather than as a background image.
  • map-card: a component that holds a static map in your view. Map card include a title-area and an on-click action, and also let you set markers (map pins).
  • compound-card: a flexible component that includes a content block (which can contain most of the non-transactional view components). (Also, see transaction properties, which are variants of cells that allow input for use with transactional workflows.)

Images

These components allow the presentation of multiple images in carousel or list form. PNG or JPG image types are recommended.

  • image-carousel: a component for multiple images, specified as a type or subtype of Image, that can be swiped through horizontally by the user.
  • image-list: a single-line list of multiple images, specified as a type or subtype of Image. If there are more images than can fit on the screen, the user can scroll the list.

Additionally, you can add a standalone image in a section's content container or in a compound-card. If you want to add an image with some overlaid text, use an image card. You can also add inline images in a single-line if you need the image to be in the same span as text.

Note

Images are only applicable to Result Moments and Confirmation Moments. For images in Input Moments, you can use an image-picker.

Partitions

The partitioned component lets you present multiple rows or lines of data with visual separation between them. It can be used to present lists, tables, and grids.

  • partitioned: used for visually separated data. It contains an unstyled title and a content block. The content block can contain most of the non-transactional view components (e.g., cards, cells, titles, and text).
  • hbox: a "horizontal box" container. An hbox contains a content child, which in turn can only contain one or more vbox components.
  • vbox: a "vertical box" container. This contains controls for horizontal and vertical alignment and a content block which can contain single-line, text, or layout-macro blocks.

A vbox container must be inside an hbox. You can think of an hbox as a row and vbox as an item in a column. The width of each column is determined by its content; Bixby will try to display the full content of each column. If there is not enough horizontal space to do so, left-aligned columns will be truncated with ellipsis marks (…); if there is still insufficient space, centered and right-aligned columns will be cut off (without the ellipsis to indicate truncation).

Note that hbox blocks do not have to be inside a partitioned block, and partitioned blocks do not have to contain hbox blocks.

Transaction Properties

Transaction properties are used within transactional workflows. They allow users to confirm actions and prompt for selections. For instance, a reservation confirmation for a restaurant might allow the user to change the party size and the reservation time.

  • input-cell: a cell wrapped in an intent, to allow a selection prompt or an input form to be presented in a confirmation-view.
  • split-input-cell: a container for two input-cell blocks. A split-input-cell has two child blocks, left and right, which each contain one and only one input-cell.

Cell Slots

The cell-area and cell-card components have columnar slots for their content, numbered slot1, slot2, and slot3:

  • slot1 appears as a square on the left side of a cell, and can only contain an image;
  • slot2 contains a content block that has primary and secondary text lines (this is not the same as a layout content block);
  • slot3 appears as a square on the right side of a cell, and can contain an image and a label.

When you lay out a cell, you can choose to have one, two, or all three slots filled, but slot2 must always be filled. So there are four possible display options:

Cells with Slots

Styling Components

Bixby Views offers limited styling of components that remain consistent with the rest of Bixby's design. All text blocks and titles can be given styles that control their size and, in some cases, a choice between normal and "soft" color. (The rendering of "Soft" styles is device-dependent, but generally has less opacity, giving it a dimmer or lighter look depending on its background.)

When styles affect size, they are listed from smallest to largest. All styling components will vary slightly on different devices and scale appropriately.

For a comparison of the styles below, see the text style reference page and the font references.

Title Styles

  • Title_XS
  • Title_S
  • Title_M
  • Title_L
  • Title_XL
  • Title_XL_Soft
  • Title_XXL
  • Title_XXL_Soft

Detail (Body Text) Styles

  • Detail_M
  • Detail_M_Soft
  • Detail_L
  • Detail_L_Soft

Other Styles

  • Legal

Image Adjustments

For a standalone image or an image in a thumbnail-card, you can set the aspect ratio of the image to the same aspect ratios as cards.

For images that are in-line with other content either horizontally (single-line) or vertically (vbox), image sizes can be set to any of the style names for Title and Detail. The image has the same height as the font size of the specified style. You should match image styles to the styles of their accompanying text, although the _Soft suffix will not affect the image's display.

Note

These ratios only apply to mobile. Image ratios on watch devices are fixed.

Additionally, you can change the position and alignment of some images using the following keys:

If you need to adjust the background of an image to either Transparent or White, you can use either image-background-color for images in cards or background-color for standalone images.

If you need to make an image clickable and show it in lightbox mode, you can use the lightbox-enabled key to indicate to the user that the image is clickable.

Image Shapes

For a comparison of the shapes, see the shape reference page.

  • Circle
  • Square

Card Aspect Ratios

You can specify the following aspect ratios for the map-card and image-card. For a visual comparison, see the aspect-ratio reference page.

  • 21:9
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
  • 9:21

Dividers

You can add a divider between content child components in compound cards and in section content components.

Design Guides and References

If you want to know which components to use during which moment in your conversation flow, you can read the Designing With Bixby Views guide.

If you want to know the design specifications of the various components or create mock-ups of your capsule's UI, you can download various files in the Design Resources topic to help you.