List Item

A row of a list: a title, with what leads it, what ends it and a line or two under it, as a list of messages, of settings or of results has.

import com.pantrixui.components.data.listitem.PantrixListItem

• Lines. headline is the row's name; supportingText a line or two under it, smaller and quieter; overline a short line over it; trailingText a short text at the end of the title's line, on its baseline: a time, a count, a setting's value. The supporting text is cut at supportingMaxLines lines, two by default.
• What leads and ends it. leading leads the row (an icon, an avatar, a picture) and trailing ends it (a badge, a tag, a switch). Both are given the row's quiet colour. chevron puts a chevron at the row's end, which says it leads on to another screen; it turns round where the layout is read from the right, and is not read out.
• Pressing and choosing. A row given onClick is one target, at least as tall as the platform's touch target, and shows the press, a faint fill under a pointer and the focus ring inside its own edges. selected fills the row in the primary role's container colour and tells a screen reader it is selected.
• One node. A screen reader hears the row as a whole: the overline, the title, the trailing text, the supporting text. A switch or a button at its end stays a node of its own.
• The line. divider draws a line under the row: Full from one side to the other, Inset from where the text starts, as iOS's lists have it.
• Platform. Material 3's rows on Android (56, 72, 88dp), iOS's on iOS (44, 60, 76), denser rows on the desktop and the web (36/52/68 and 40/56/72). The title is set in the body type on a phone and in the label type on the desktop and the web; headlineStyle, supportingTextStyle and trailingTextStyle change them.

Examples

An inbox

An inbox: who wrote, when, and about what. A press on a row chooses it; the chosen row is filled. The lines are drawn from where the text starts, and leave the column of avatars whole.

var open by remember { mutableStateOf("0") }
Column {
    INBOX.forEachIndexed { index, mail ->
        PantrixListItem(
            headline = mail.from,
            supportingText = mail.subject,
            trailingText = mail.time,
            leading = { PantrixAvatar(contentDescription = null, initials = mail.initials) },
            selected = open == "$index",
            onClick = { open = "$index" },
            divider = ListItemDivider.Inset,
            tagKey = "mail_$index"
        )
    }
}

private class InboxMessage(
    val from: String,
    val initials: String,
    val subject: String,
    val time: String
)

private val INBOX = listOf(
    InboxMessage("Ayşe Demir", "AD", "The agenda of Monday's meeting", "12:40"),
    InboxMessage("Mert Kaya", "MK", "The design files are ready", "11:05"),
    InboxMessage("Elif Şahin", "EŞ", "Invoice: October", "Yesterday")
)

Settings

Settings: the rows that lead on to another screen have their values and a chevron at their end. The notifications' row is not pressed; the switch at its end is a control of its own. A row that is turned off takes no press and is written faintly.

var notify by remember { mutableStateOf(true) }
Column {
    PantrixListItem(
        headline = "Downloads",
        trailingText = "Wi-Fi only",
        leading = { PantrixIcon(PantrixIcons.Download, contentDescription = null) },
        chevron = true,
        onClick = {},
        divider = ListItemDivider.Full,
        tagKey = "downloads"
    )
    PantrixListItem(
        headline = "Notifications",
        supportingText = "When a new message comes",
        leading = { PantrixIcon(PantrixIcons.Inbox, contentDescription = null) },
        trailing = {
            PantrixSwitchButton(
                checked = notify,
                onCheckedChange = { notify = it },
                contentDescription = "Notifications",
                tagKey = "notify"
            )
        },
        divider = ListItemDivider.Full,
        tagKey = "notifications"
    )
    PantrixListItem(
        headline = "Backup",
        supportingText = "Not in your plan",
        leading = { PantrixIcon(PantrixIcons.Upload, contentDescription = null) },
        chevron = true,
        onClick = {},
        enabled = false,
        tagKey = "backup"
    )
}

Three lines

Three lines, read and not pressed: the date over it, up to two lines of supporting text under it, a tag at its end. In a row of three lines what leads and ends it stands at its top.

Column {
    PantrixListItem(
        headline = "Order 1042",
        overline = "28 October",
        supportingText = "Two books and a notebook. Shipped, and expected to arrive tomorrow.",
        trailing = { PantrixTag(text = "On its way", tone = TagTone.Info) },
        divider = ListItemDivider.Full,
        tagKey = "order_1042"
    )
    PantrixListItem(
        headline = "Order 1039",
        overline = "21 October",
        supportingText = "A pair of headphones.",
        trailing = { PantrixTag(text = "Delivered", tone = TagTone.Success) },
        tagKey = "order_1039"
    )
}

What a search found

A search's results: the word searched for is set in bold in the title (the overload that takes an AnnotatedString), and the supporting text says where it was found.

val typed = "Area"
Column {
    listOf("Text Area", "Filled Text Area").forEachIndexed { index, title ->
        val at = title.indexOf(typed)
        PantrixListItem(
            headline = buildAnnotatedString {
                append(title.take(at))
                withStyle(SpanStyle(fontWeight = FontWeight.ExtraBold)) { append(typed) }
                append(title.drop(at + typed.length))
            },
            supportingText = "Component · Form",
            leading = { PantrixIcon(PantrixIcons.Search, contentDescription = null) },
            onClick = {},
            tagKey = "found_$index"
        )
    }
}

A style and colours of its own

A style and colours of its own: denser rows (ListItemStyle), the title in the theme's callout role, the selected row in a success colour (ListItemColors), the supporting text in the footnote type (supportingTextStyle), the price in the code type (trailingTextStyle).

val success = PantrixTheme.colors.success
var chosen by remember { mutableStateOf(0) }
Column {
    listOf("Weekly" to "29 ₺", "Monthly" to "99 ₺", "Yearly" to "990 ₺").forEachIndexed { index, (plan, price) ->
        PantrixListItem(
            headline = plan,
            supportingText = if (index == 2) "Two months on us" else null,
            trailingText = price,
            selected = chosen == index,
            onClick = { chosen = index },
            style = ListItemStyle(oneLineHeight = 40.dp, twoLineHeight = 52.dp, headlineRole = TypeRole.Callout),
            colors = ListItemColors(selectedContainer = success.container, selectedContent = success.onContainer),
            supportingTextStyle = PantrixTheme.typography.footnote,
            trailingTextStyle = PantrixTheme.typography.code,
            tagKey = "plan_$index"
        )
    }
}

API

headline

A row of a list: a title, with what leads it, what ends it and a line or two under it, as a list of messages, of settings or of results has.

headline

A row of a list whose title has more in it than words: a word marked where a search found it, a part in bold.

ListItemStyle

PantrixListItem's geometry and type: how tall a row of one, two and three lines is at the least, the room around and between what it holds, the corners of its fill and the types it writes in.

ListItemColors

What a PantrixListItem is painted with, where it is not the theme's: a colour that is set is used, and one that is left out stays the theme's.