Alert

A message about what the user is doing, shown beside the thing it is about: the form that was just sent, the row about to be deleted, the one field that needs a second look.

import com.pantrixui.components.container.alert.PantrixAlert

Six tones. tone chooses the alert's colour, its icon and how it is announced. The four semantic tones, Info, Success, Warning and Danger, say how something went in three ways: a colour alone fails whoever cannot see it. Primary and Neutral say nothing of that, and have no icon of their own.
Three variants. variant: Soft is the tone's pale fill, Outline an edge with no fill, and Accent the fill with a bar down its leading edge: on the left in a left-to-right layout, on the right in a right-to-left one.
A message with a link. message can be an AnnotatedString too: a LinkAnnotation in it becomes a link, underlined, in the alert's text colour.
Title and icon. title is a line above the message, in a heavier type. icon puts another icon in place of the tone's own, or takes the icon away with null.
Action. action puts one or two small buttons under the message, at the trailing edge.
Dismissal. With onDismiss the alert has a close button. An alert does not go away by itself: it stays until the caller stops showing it.
First line. The icon and the close button stand on the text's first line, however large the type is set. An alert with an icon and one without are as tall as each other.
Platform. The corners are medium on Android and iOS, and small on desktop and the web; the padding is 12dp and 10dp, and the bar 4dp and 3dp (AlertStyle).
Text. textStyle changes the type of the message, and of the title in its bold; the icon and the close button stand on that type's first line.
Colours of its own. AlertColors gives the fill, the colour of the text and of what marks the tone, and border the colour of an edge apart from the icon's; the tone still decides the icon and the way the alert is announced.
Automation. With tagKey the alert is Alert_<tagKey> and its close button AlertClose_<tagKey>. A dismissal is reported with its tone and its variant, and never with its message.

Examples

Message and title

The least it takes is message alone: the tone is then Info and the variant Soft, and the icon comes from the tone. The alert fills the width it is given.

title puts a line in a heavier type above the message: it says in a few words what the alert is about. A screen reader hears the title and the message as one.

PantrixAlert(message = "Your profile photo has been updated", tagKey = "plain")
PantrixAlert(
    message = "We have sent a verification link to your new address",
    title = "Verify your email",
    tagKey = "titled"
)

Six tones

tone is one of the theme's colour roles; it chooses the alert's colour, its icon and how it is announced to a screen reader, all at once. The four semantic tones reach the user three ways: as a colour, as an icon and in the way they are announced. Danger is the one tone announced assertively.

Primary and Neutral do not say how something went, and have no icon. An alert in one of them is a note set apart from the text around it: a feature to try, something to know that does not ask for the eye.

PantrixAlert(message = "A new version is ready to install", tagKey = "info")
PantrixAlert(message = "Your changes have been saved", tone = AlertTone.Success, tagKey = "success")
PantrixAlert(message = "Your storage is almost full", tone = AlertTone.Warning, tagKey = "warning")
PantrixAlert(message = "The message could not be sent", tone = AlertTone.Danger, tagKey = "danger")
PantrixAlert(message = "Try the new editor", tone = AlertTone.Primary, tagKey = "primary")
PantrixAlert(message = "Last opened: yesterday", tone = AlertTone.Neutral, tagKey = "neutral")

Three variants

variant chooses how the alert is drawn: a pale fill, an edge alone, or the fill with a bar down its leading edge. Soft is the default, and what a page wants. Accent tells alerts one under another apart at a glance.

Outline is for a card or a dialog: a pale fill would be lost on their own fill. The one here is inside a filled card: it has no fill of its own, so the card's fill shows, and its text is written in the colour that reads on the card. This alert's announce is false as well: a note that was there before the user came is not announced when it appears.

PantrixAlert(
    message = "A pale fill: this is how it looks on a page",
    title = "Soft",
    tagKey = "soft"
)
PantrixCard(modifier = Modifier.fillMaxWidth(), variant = CardVariant.Filled) {
    PantrixAlert(
        message = "Archived records cannot be changed",
        variant = AlertVariant.Outline,
        title = "Outline: read-only",
        // It was already here when the user came: a screen reader gets to it in its own time.
        announce = false,
        tagKey = "outline"
    )
}
PantrixAlert(
    message = "Alerts one under another are told apart at a glance",
    tone = AlertTone.Success,
    variant = AlertVariant.Accent,
    title = "Accent",
    tagKey = "accent"
)

Changing and removing the icon

icon is the mark before the text: the tone's own unless one is given, and none when null. The Primary and Neutral tones have no icon of their own; here each of them was given one. The icon is never read out: the message says what it stands for.

An alert with an icon and one without are as tall as each other: the text's first line takes the room of an icon, with one beside it or without.

PantrixAlert(message = "An info note with its icon removed", icon = null, tagKey = "no_icon")
PantrixAlert(
    message = "Added to your favourites",
    tone = AlertTone.Primary,
    icon = PantrixIcons.Star,
    tagKey = "star_icon"
)
PantrixAlert(
    message = "The meeting is at 10.00 tomorrow",
    tone = AlertTone.Neutral,
    icon = PantrixIcons.Calendar,
    tagKey = "calendar_icon"
)

Action and dismissal

A warning with two actions and a close button. action puts the buttons under the message, at the trailing edge. A text button's own colour is the brand's; buttonColors(ButtonVariant.Text), taken from the tone's role, draws it in the tone's colour, which reads on the tone's fill.

There is a close button because onDismiss is given. Press the cross or "Later": it is the screen's state that takes the alert away, not the alert; the button that brings it back takes its place. Someone using a screen reader can also close the alert with the dismiss action, without finding the button.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
var shown by rememberSaveable { mutableStateOf(true) }
// A text button's own colour is the brand's; on the alert's fill it is the tone's own colour that reads.
val inTheTone = PantrixTheme.colors.warning.buttonColors(ButtonVariant.Text)
if (shown) {
    PantrixAlert(
        message = "New photos may not be backed up",
        tone = AlertTone.Warning,
        variant = AlertVariant.Accent,
        title = "Your storage is almost full",
        action = {
            PantrixButton(
                text = "Later",
                onClick = { shown = false },
                variant = ButtonVariant.Text,
                size = ButtonSize.Small,
                colors = inTheTone,
                tagKey = "storage_later"
            )
            PantrixButton(
                text = "Manage",
                onClick = { scope.launch { snackbars?.show(message = "Storage opened", tagKey = "storage") } },
                variant = ButtonVariant.Text,
                size = ButtonSize.Small,
                colors = inTheTone,
                tagKey = "storage_manage"
            )
        },
        onDismiss = { shown = false },
        tagKey = "storage"
    )
} else {
    PantrixButton(
        text = "Show the warning again",
        onClick = { shown = true },
        variant = ButtonVariant.Outline,
        tagKey = "storage_again"
    )
}

Form error

A form that fails when it is sent. Press "Send": the error alert appears above the button at once. Because its tone is Danger, it is announced to a screen reader straight away, interrupting what it is saying. The cross takes it away.

var failed by rememberSaveable { mutableStateOf(false) }
if (failed) {
    PantrixAlert(
        message = "Check the address and try again in a few minutes",
        tone = AlertTone.Danger,
        title = "Sending failed",
        onDismiss = { failed = false },
        tagKey = "form_error"
    )
}
PantrixButton(text = "Send", onClick = { failed = true }, tagKey = "form_send")

A message with a link

The message can be an AnnotatedString too: to set a word in bold, or to put a link in it. A link is a LinkAnnotation; the alert draws it in its text's colour, underlined. A LinkAnnotation.Clickable does the app's own work when it is pressed, a LinkAnnotation.Url opens its address in the browser.

val report = LocalExampleEvents.current
PantrixAlert(
    message = buildAnnotatedString {
        append("This page goes away in the next release. Read ")
        withLink(LinkAnnotation.Clickable(tag = "guide") { report("New guide opened") }) {
            append("the new guide")
        }
        append(" instead.")
    },
    tone = AlertTone.Warning,
    title = "Old page",
    tagKey = "with_link"
)

In its own colours

An alert whose fill, text and marks are in colours the caller gives. AlertColors takes three colours: the fill (container), the text (content) and what marks the tone (accent): the icon, the edge of Outline and the bar of Accent. A colour that is left out stays the tone's. The tone still gives the alert its icon and the way it is announced: only what it is painted in changes.

val own = ownColors()
PantrixAlert(
    message = "The colours of its fill, its text and its marks were given by the caller",
    variant = AlertVariant.Accent,
    colors = AlertColors(container = own.container, content = own.onContainer, accent = own.color),
    tagKey = "own"
)
PantrixText(
    text = "Colours are given with AlertColors; a colour that is left out stays the tone's.",
    style = PantrixTheme.typography.footnote,
    color = PantrixTheme.colors.textSecondary
)

In its own style

style changes the alert's geometry: its corners, its padding, the room between its parts, and how thick the edge of Outline and the bar of Accent are. Only the fields that are set change; the rest comes from the platform's style.

The third is a note: its fill and its icon are the tone's, its edge a colour apart from them (AlertColors(border = …)), its padding one across and another up and down (horizontalPadding, verticalPadding), and its text the theme's label (textStyle): the icon and the close button stand on that text's first line, and its colour is still the alert's.

PantrixAlert(
    message = "Square corners, bar 8dp",
    tone = AlertTone.Success,
    variant = AlertVariant.Accent,
    style = AlertStyle(shape = ShapeSpec.Fixed(RectangleShape), accentWidth = 8.dp),
    tagKey = "own_style_accent"
)
PantrixAlert(
    message = "Padding 20dp, edge 2dp",
    tone = AlertTone.Warning,
    variant = AlertVariant.Outline,
    style = AlertStyle(padding = 20.dp, borderWidth = 2.dp),
    tagKey = "own_style_outline"
)
PantrixAlert(
    message = "An edge in a colour apart from the fill and the icon; padding of 14 across and 10dp up and down; text the size of a label",
    tone = AlertTone.Warning,
    style = AlertStyle(horizontalPadding = 14.dp, verticalPadding = 10.dp),
    colors = AlertColors(border = PantrixTheme.colors.warning.color.copy(alpha = 0.45f)),
    tagKey = "own_style_note",
    textStyle = PantrixTheme.typography.label
)

API

message

A message about what the user is doing, shown beside the thing it is about: the form that was just sent, the row about to be deleted, the one field that needs a second look.

Parameter	Type	Default	What it is
`message`	`String`		what happened, or what to know: a sentence or two.
`modifier`	`Modifier`	`Modifier`	the alert's modifier. The alert fills the width it is given.
`tone`	`AlertTone`	`AlertTone.Info`	what the alert is telling: its colours, its icon and the way it is announced.
`variant`	`AlertVariant`	`AlertVariant.Soft`	how it is drawn: a pale fill, an edge alone, or the fill with a bar.
`title`	`String?`	`null`	a line above the message, in a heavier type: what it is about, in a few words.
`icon`	`ImageVector?`	`tone.icon()`	the mark before the text: the tone's own unless another is given, and none when null. A primary and a neutral alert have none of their own. It is never read out: the message says what it stands for. `icon`: The tone's own icon; a primary and a neutral alert have none.
`action`	`(@Composable RowScope.() -> Unit)?`	`null`	what the user can do about it, under the message at the end: one or two small buttons. A text button's own colour is the brand's: `PantrixTheme.colors.warning.buttonColors(ButtonVariant.Text)` draws it in the tone's, which reads on the tone's fill. A button there takes the room it is drawn in: the room a finger needs around it reaches into the alert's padding, and the alert is no taller for it.
`onDismiss`	`(() -> Unit)?`	`null`	called when the close button is pressed, or a screen reader's dismiss action is used. Null leaves the button out. The alert stays until the caller stops showing it.
`announce`	`Boolean`	`true`	whether a screen reader is told when the alert appears or changes: assertively for `AlertTone.Danger`, politely for the rest. Turn it off for an alert that was there before the user came, as a note that a record cannot be changed: a screen reader gets to it in its own time.
`style`	`AlertStyle?`	`null`	this call's own style: over every enclosing one and under the density. Only the fields it sets change, on every platform.
`colors`	`AlertColors?`	`null`	this alert's own colours, where they are not its tone's: the ones set here, with the tone's for the rest.
`tagKey`	`String?`	`null`	the alert's automation key: the alert is `Alert_<tagKey>` and its close button `AlertClose_<tagKey>`. A dismissal is reported as an `Alert` event, `dismiss`, with the tone and the variant and never the message.
`textStyle`	`TextStyle`	`PantrixTheme.typography.body`	the type the message is set in, and the title in its bold: the theme's `body` unless given. A colour in it is not the text's, which is the alert's.

message

PantrixAlert for a message with more in it than words: a value set as code, a word set in bold, a link to the page that says more. It is drawn, announced and reported as the other form is; a screen reader hears the message's words with the title, and reaches each link on its own, as it reaches the action.

Parameter	Type	Default	What it is
`message`	`AnnotatedString`		what happened, or what to know, with its spans and links.
`modifier`	`Modifier`	`Modifier`	the alert's modifier. The alert fills the width it is given.
`tone`	`AlertTone`	`AlertTone.Info`	what the alert is telling: its colours, its icon and the way it is announced.
`variant`	`AlertVariant`	`AlertVariant.Soft`	how it is drawn: a pale fill, an edge alone, or the fill with a bar.
`title`	`String?`	`null`	a line above the message, in a heavier type: what it is about, in a few words.
`icon`	`ImageVector?`	`tone.icon()`	the mark before the text: the tone's own unless another is given, and none when null. `icon`: The tone's own icon; a primary and a neutral alert have none.
`action`	`(@Composable RowScope.() -> Unit)?`	`null`	what the user can do about it, under the message at the end: one or two small buttons.
`onDismiss`	`(() -> Unit)?`	`null`	called when the close button is pressed, or a screen reader's dismiss action is used. Null leaves the button out.
`announce`	`Boolean`	`true`	whether a screen reader is told when the alert appears or changes.
`style`	`AlertStyle?`	`null`	this call's own style: over every enclosing one and under the density.
`colors`	`AlertColors?`	`null`	this alert's own colours, where they are not its tone's.
`tagKey`	`String?`	`null`	the alert's automation key: the alert is `Alert_<tagKey>` and its close button `AlertClose_<tagKey>`.
`textStyle`	`TextStyle`	`PantrixTheme.typography.body`	the type the message is set in, and the title in its bold: the theme's `body` unless given. A colour in it is not the text's, which is the alert's.

AlertStyle

PantrixAlert's geometry: its corners, the room around what it holds and between its parts, and the two lines its variants draw, an edge all the way round or a bar down the leading edge.

Parameter	Type	Default	What it is
`shape`	`ShapeSpec`	`ShapeSpec.Unspecified`	The alert's corners: medium on Android and iOS, small on desktop and the web.
`padding`	`Dp`	`Dp.Unspecified`	The room between the alert's edge and what it holds: 12dp on Android and iOS, 10dp on desktop and the web.
`contentGap`	`Dp`	`Dp.Unspecified`	The room between the icon and the text, and between the text and the close button: 8dp.
`borderWidth`	`Dp`	`Dp.Unspecified`	How thick the edge of `AlertVariant.Outline` is: 1dp.
`accentWidth`	`Dp`	`Dp.Unspecified`	How wide the bar of `AlertVariant.Accent` is: 4dp on Android and iOS, 3dp on desktop and the web.
`horizontalPadding`	`Dp`	`Dp.Unspecified`	The room between the alert's start and end edges and what it holds, where it is not `padding`: unspecified on every platform, which takes `padding`.
`verticalPadding`	`Dp`	`Dp.Unspecified`	The room between the alert's top and bottom edges and what it holds, where it is not `padding`: unspecified on every platform, which takes `padding`.

AlertColors

What PantrixAlert is painted with, for an alert that does not take its tone's colours: a colour that is set is used, and one that is left out stays the tone's.

Parameter	Type	Default	What it is
`container`	`Color`	`Color.Unspecified`	The alert's fill. The `container` of its tone's role; none in `AlertVariant.Outline`, which shows what the alert stands on.
`content`	`Color`	`Color.Unspecified`	The title and the message, what the action is drawn in unless it has a colour of its own, and the close button's cross: the colour that reads on `container`. The `onContainer` of its tone's role. None in `AlertVariant.Outline`, where the alert has no fill: its text is drawn as a text is where the alert stands, `textPrimary` on the page and the content colour of a fill around it.
`accent`	`Color`	`Color.Unspecified`	What marks the tone: the icon, the edge of `AlertVariant.Outline` unless `border` is given, and the bar of `AlertVariant.Accent`. The `color` of its tone's role.
`border`	`Color`	`Color.Unspecified`	The edge all the way round the alert, at the style's `borderWidth`, where it is not the icon's colour: an alert of any variant given one draws it, over its fill and beside the bar of `AlertVariant.Accent`. Left out, `AlertVariant.Outline`'s edge is `accent` and the other two variants draw none.

Accessibility

Screen reader. The title and the message are read as one, and the action and the close button after them. The alert is announced when it appears or changes: assertively for Danger, politely for the rest. announce = false turns this off.