Alert Dialog
The Alert Dialog is a modal window that blocks content, providing critical information that requires a decision.
Alert Dialog vs. Modal
The Alert Dialog component is the mobile equivalent of Modal for web. Both components popup over existing content and are accompanied by an overlay.
Anatomy
- Overlay: Scrim for added emphasis.
- Message Container: Contains all the elements of the Alert Dialog.
- Title (Optional): Header text.
- Message: A concise message no longer than 4 lines.
- Buttons: Actions related to the message.
Usage Guidance
Alert Dialogs are reserved for messages of the highest priority due to their blocking behavior. Disabling a user’s task while providing information without an actionable outcome may lead to frustration.
When to Use
- To communicate critical information that requires user decision or action.
When to Consider Something Else
- Avoid an Alert Dialog for low or medium priority messaging. The Alert Dialog disables all functionality until action has been taken, distracting a user from their task at hand.
- Consider using Banners if communicating errors or warnings about a task. Please note that Banners do not disappear unless the user resolves the required action.
- Consider using Snackbars when communicating updates about a process. Snackbars do not require user action.
- When no content can display on a page (due to a server error or connectivity issue, for example), use an Empty State, use the full page to communicate the status of the feature or to help educate users about its purpose. Empty states should include a message.
Behaviors
Alert Dialogs block content ― providing critical information and requiring a decision ― by appearing above screen UI elements and disabling all functionality until action has been taken.
Examples
Padding
Left and right margins vary across device types.
Action Styling
The Alert Dialog supports 1 or 2 actions. When there are 2 horizontal action buttons, the primary button should always be on the right.
If button labeling breaks the built in padding requirements for horizontal alignment (e.g., buttons with long labels or with internationalization issues), use stacked buttons instead.
Titling
Titles are optional but recommended to increase clarity. Titles should contain a brief and clear statement but may extend to 2 lines if needed.
Do
Use titles that are short and concise, explain the request, and give clear actions.
Don't
Use titles that ask a question or make it unclear how to proceed.
API Guidelines
Methods
Class name: AlertUIComponent Module name: UIComponentsPlugin
public init(
featureData: FeatureMetricsData,
title: String,
message: String? = nil,
show: Binding<Bool>,
mainButtonType: AlertMainButtonType,
mainButtonConfig: AlertButtonConfig? = nil,
auxiliaryButtonConfig: AlertButtonConfig? = nil
)Parameters
| Name | Description | Default values |
|---|---|---|
| featureData | the feature name/context and the screen ID in which the component appears. | |
| title | Title of the alert, displayed on top. Needs to be passed after localization. | |
| message | Message of the alert, displayed below the title. Needs to be passed after localization. | nil |
| show | Boolean binding that controls the visibility of the component. | |
| mainButtonType | AlertMainButtonType representing the type of the main button. | |
| mainButtonConfig | Optional AlertButtonConfig having the information to display an action button. If a value is not provided, we will render a primary button with a title of “Ok” if the mainButtonType is primary/secondary and a delete button with a title of “Delete” if the mainButtonType is delete. | nil |
| auxiliaryButtonConfig | Optional AlertButtonConfig having the information to display an additional action button. If a value is not provided, we will render a secondary button with a title of “Cancel”. | nil |
Accessibility Guidelines
Coming soon…
Content Guidelines
- In titles, avoid apologies (i.e., sorry, please, etc…), or additional written level of emphasis (e.g., warning).
- See Popups, Modals, and Dialogs in the UI Text Section of Content Style Guide for additional Alert Dialog language guidelines.
Alert Dialog vs. Modal
The Alert Dialog component is the mobile equivalent of Modal for web. Both components popup over existing content and are accompanied by an overlay.
Anatomy
- Overlay: Scrim for added emphasis.
- Message Container: Contains all the elements of the Alert Dialog.
- Title (Optional): Header text.
- Message: A concise message no longer than 4 lines.
- Buttons: Actions related to the message.
Usage Guidance
Alert Dialogs are reserved for messages of the highest priority due to their blocking behavior. Disabling a user’s task while providing information without an actionable outcome may lead to frustration.
When to Use
- To communicate critical information that requires user decision or action.
When to Consider Something Else
- Avoid an Alert Dialog for low or medium priority messaging. The Alert Dialog disables all functionality until action has been taken, distracting a user from their task at hand.
- Consider using Banners if communicating errors or warnings about a task. Please note that Banners do not disappear unless the user resolves the required action.
- Consider using Snackbars when communicating updates about a process. Snackbars do not require user action.
- When no content can display on a page (due to a server error or connectivity issue, for example), use an Empty State, use the full page to communicate the status of the feature or to help educate users about its purpose. Empty states should include a message.
Behaviors
Alert Dialogs block content ― providing critical information and requiring a decision ― by appearing above screen UI elements and disabling all functionality until action has been taken.
Examples
Padding
Left and right margins vary across device types.
Action Styling
The Alert Dialog supports 1 or 2 actions. When there are 2 horizontal action buttons, the primary button should always be on the right.
If button labeling breaks the built in padding requirements for horizontal alignment (e.g., buttons with long labels or with internationalization issues), use stacked buttons instead.
Titling
Titles are optional but recommended to increase clarity. Titles should contain a brief and clear statement but may extend to 2 lines if needed.
Do
Use titles that are short and concise, explain the request, and give clear actions.
Don't
Use titles that ask a question or make it unclear how to proceed.
API Guidelines
@Composable
fun AlertDialogUiComponent(
modifier: Modifier = Modifier,
titleText: String? = null,
promptText: String? = null,
alertDialogConfig: AlertDialogConfig = AlertDialogConfig.DEFAULT,
positiveButtonText: String = determineDefaultButtonText(alertDialogConfig),
negativeButtonText: String = WorkdayTheme.canvasLocalization.cancel(),
onPositiveButtonClick: () -> Unit = { },
onNegativeButtonClick: () -> Unit = { },
)Props
| Name | Type | Default | Description |
| ------------------------- | ------------------- | --------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | --- |
| titleText | String? | Null | Optional text for bolded title at top of dialog. Will not display if value is null | |
| promptText | String? | Null | Optional text for the main message of the dialog. Will not display if value is null |
| alertDialogConfig | AlertDialogConfig | default | Enum to select different variations of the alert dialog |
| positiveButtonText | String | OK/DELETE | Optional text for the positive button (Default value will be determined by the alertDialogConfig. Delete variation will have a default “Delete” text and other variations will be a default “OK” text) |
| negativeButtonText | String | Cancel | Optional text for the negative button (Default value will be “Cancel”) |
| onPositiveButtonClick | () -> Unit | | Callback for when the positive button is clicked. |
| onNegativeButtonClick | () -> Unit | | Callback for when the negative button is clicked |
Accessibility Guidelines
Coming soon…
Content Guidelines
- In titles, avoid apologies (i.e., sorry, please, etc…), or additional written level of emphasis (e.g., warning).
- See Popups, Modals, and Dialogs in the UI Text Section of Content Style Guide for additional Alert Dialog language guidelines.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #ask-canvas-design or #ask-canvas-kitchannels on Slack.