Intro

The card header is the uppermost part of the card that provides important information about the card and its related content on the detail page. The optional card header allows for a quick overview of key information, such as a title, subtitle, and status of the card.

Card header examples

Card header examples

Usage

Use a card header to include essential information about the content of a card.

Don't

Don’t use the card header to provide more detailed information on the card, use the card body instead.

In the main card header, you can include a title, subtitle, left accessory, icon button, a counter and/or a custom composable.
In the extended card header, you can include a status info label, rating controls, tags, text, a KPI, and/or a custom composable.
Use a maximum of three rows for both the main and extended card header.
Use only an icon button within the card header that directly impacts the card, for example, to favorite or bookmark the card.
Make sure that the title on the header image has a good contrast to the image. For example, use a white title on a darker image and a black title on a lighter image.
Maintain consistent positioning of the components in the card header throughout the app. For example, if one card header contains tags in the first line, all the other cards in your app should have them too.
Use a counter only if the card body includes list components such as card cells or data table.
Don’t place other components, such as a key value cell or an avatar row component, in the card header. Use the card body instead.

Cards with good title contrast on image

Cards with good title contrast on image

Cards with bad title contrast on image

Cards with bad title contrast on image

Card with well-balanced content OR: card with recommended number of elements in card header

Card with recommended number of elements in card header

Card with too many elements in the card header

Card with too many elements in the card header

Anatomy

A. Card Header Container

The header container is the element that holds the header image, main header, and extended header of the card.

B. Card Header Image (Media)

The header image, also known as media in the SDK, is an optional decorative element that allows you to include an image that matches the card context.

C. Main Header (Optional)

The main header contains essential information about the card, such as a title, subtitle, left and right accessory.

D. Extended Header

The extended header contains additional elements that provide more information, such as a status info label, rating controls, tags, or text.

On the right side of the extended header, an adaptable slot can be added to display a KPI or a custom component.

Card header anatomy

Card header anatomy

Variations

Main Card Header Components

Every component in the main card header is optional, including the title. If the header image already has a title, it's best not to repeat it or use it for other details in the main header.

A. Title

B. Subtitle

C. Left Accessory

The left accessory provides one slot for either an avatar or a v-stacked status info label. It is designed to hug the content and expands to the right if needed, limiting the space available for the title and subtitle.

D. Right Accessory

The right accessory can accommodate up to two UI elements, including an icon button, a counter, or a custom composable. Due to limited space, it's best to use compact custom components. The right accessory is designed to hug the content and expands to the left if needed, limiting the space available for the title and subtitle.

Counter: The counter indicates the number of list items shown in a card and the total number of list items in a list report. The SDK provides a string, however, you need to implement the counter's logic based on the dataset it is referencing.

Schematic examples (left) and main card header components (right)

Extended Card Header Components

Every element in the extended header is optional. To maintain consistency, it’s best to arrange the components in the same order across different rows. For example, if your card includes a status in the first row, it’s recommended to place the status in the same position for other cards throughout your app.

A. Status Info Label

B. Text

C. Rating Control

D. Tags

E. Right Accessory

The flexible slot is designed to hold either a KPI or a custom composable, and it takes precedence by limiting horizontal space for other elements in the extended card header.

If only one or two rows are displayed alongside the right accessory, the UI elements are aligned side by side. If the right accessory is the sole element, it can be placed to the left, center, or right within the extended header.

Row Behavior/Configuration:

Three rows with right accessory: Each row is limited to one line and can display an UI element, such as tags or description. The second and third rows are grouped with the right accessory beside them. The first row appears above this group and spans the full width of the extended header.
Two rows with right accessory: Each row is limited to one line and can display an UI element, such as tags or a description. Both rows are placed next to the accessory.
One row with right accessory: The row is limited to one line and can display an UI element, such as tags or description. The row is positioned next to the accessory.
Wrapping row: A row with a single UI element can wrap up to three lines and fill the extended header container.
Right accessory only: The right accessory is set to hug and expands as needed.

Schematic examples (left) and extended header components (right)

Behavior and Interaction

Users can open a menu with host actions that directly impact the card, such as hiding the card. To close the menu, users can tap anywhere on the card or tap the icon button again.

Overflow menu interaction