Build apps faster with our new App builder! Check it out →

TitleCard

Android

Component in Wear Material 3 Compose

Opinionated Wear Material 3 [Card] that offers a specific layout to show interactive information about an application, e.g. a message. TitleCards are designed for use within an application.

The [time], [subtitle] and [content] fields are optional, but it is expected that at least one of these is provided. The layout will vary according to which fields are supplied - see samples.

If the [content] is text it can be single or multiple line and is expected to be Top and Start aligned. When [subtitle] is used [content] shouldn't exceed 2 lines height. Overall the [title], [content] and [subtitle] text should be no more than 5 rows of text combined.

If more than one composable is provided in the [content] slot it is the responsibility of the caller to determine how to layout the contents, e.g. provide either a row or a column.

Last updated:

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha27")
}

Overloads

@Composable
fun TitleCard(
    onClick: () -> Unit,
    title: @Composable RowScope.() -> Unit,
    modifier: Modifier = Modifier,
    onLongClick: (() -> Unit)? = null,
    onLongClickLabel: String? = null,
    time: @Composable (() -> Unit)? = null,
    subtitle: @Composable (ColumnScope.() -> Unit)? = null,
    enabled: Boolean = true,
    shape: Shape = CardDefaults.shape,
    colors: CardColors = CardDefaults.cardColors(),
    border: BorderStroke? = null,
    contentPadding: PaddingValues = CardDefaults.ContentPadding,
    interactionSource: MutableInteractionSource? = null,
    content: @Composable (() -> Unit)? = null,
)

Parameters

namedescription
onClickWill be called when the user clicks the card
titleA slot for displaying the title of the card, expected to be one or two lines of text.
modifierModifier to be applied to the card
onLongClickCalled when this card is long clicked (long-pressed). When this callback is set, [onLongClickLabel] should be set as well.
onLongClickLabelSemantic / accessibility label for the [onLongClick] action.
timeAn optional slot for displaying the time relevant to the contents of the card, expected to be a short piece of text. Depending on whether we have a [content] or not, can be placed at the end of the [title] line or above it.
subtitleAn optional slot for displaying the subtitle of the card, expected to be one line of text.
enabledControls the enabled state of the card. When false, this card will not be clickable and there will be no ripple effect on click. Wear cards do not have any specific elevation or alpha differences when not enabled - they are simply not clickable.
shapeDefines the card's shape. It is strongly recommended to use the default as this shape is a key characteristic of the Wear Material Theme
colors[CardColors] that will be used to resolve the colors used for this card in different states. See [CardDefaults.cardColors].
borderA BorderStroke object which is used for drawing outlines.
contentPaddingThe spacing values to apply internally between the container and the content
interactionSourcean optional hoisted [MutableInteractionSource] for observing and emitting [Interaction]s for this card. You can use this to change the card's appearance or preview the card in different states. Note that if null is provided, interactions will still happen internally.
contentThe optional body content of the card. If not provided then title and subtitle are expected to be provided

Code Examples

TitleCardSample

@Composable
fun TitleCardSample() {
    TitleCard(
        onClick = { /* Do something */ },
        title = { Text("Title card") },
        time = { Text("now") },
    ) {
        Text("Card content")
    }
}

TitleCardWithImageBackgroundSample

@Composable
fun TitleCardWithImageBackgroundSample() {
    TitleCard(
        onClick = { /* Do something */ },
        title = { Text("Card title") },
        time = { Text("now") },
        colors =
            CardDefaults.imageCardColors(
                containerPainter =
                    CardDefaults.imageWithScrimBackgroundPainter(
                        backgroundImagePainter = painterResource(id = R.drawable.backgroundimage)
                    ),
                contentColor = MaterialTheme.colorScheme.onSurface,
                titleColor = MaterialTheme.colorScheme.onSurface
            ),
        contentPadding = CardDefaults.ImageContentPadding,
        modifier = Modifier.semantics { contentDescription = "Background image" }
    ) {
        Text("Card content")
    }
}

TitleCardWithSubtitleAndTimeSample

@Composable
fun TitleCardWithSubtitleAndTimeSample() {
    TitleCard(
        onClick = { /* Do something */ },
        time = { Text("now") },
        title = { Text("Title card") },
        subtitle = { Text("Subtitle") }
    )
}

TitleCardWithMultipleImagesSample

@Composable
fun TitleCardWithMultipleImagesSample() {
    TitleCard(
        onClick = { /* Do something */ },
        title = { Text("Title card") },
        time = { Text("now") },
        modifier = Modifier.semantics { contentDescription = "Background image" }
    ) {
        Spacer(Modifier.height(4.dp))
        Row(modifier = Modifier.fillMaxWidth()) {
            Image(
                modifier =
                    Modifier.weight(2f)
                        .height(68.dp)
                        .align(Alignment.CenterVertically)
                        .clip(RoundedCornerShape(16.dp)),
                painter = painterResource(id = R.drawable.card_content_image),
                contentScale = ContentScale.Crop,
                contentDescription = null
            )
            Spacer(Modifier.width(4.dp))
            Image(
                modifier =
                    Modifier.weight(1f)
                        .height(68.dp)
                        .align(Alignment.CenterVertically)
                        .clip(RoundedCornerShape(16.dp)),
                painter = painterResource(id = R.drawable.card_content_image),
                contentScale = ContentScale.Crop,
                contentDescription = null
            )
        }
    }
}

OutlinedTitleCardSample

@Composable
fun OutlinedTitleCardSample() {
    TitleCard(
        onClick = { /* Do something */ },
        title = { Text("Title card") },
        time = { Text("now") },
        colors = CardDefaults.outlinedCardColors(),
        border = CardDefaults.outlinedCardBorder(),
    ) {
        Text("Card content")
    }
}
by @alexstyl