Dialog

Updated: Apr 23, 2024

Overview

Dialogs are modal windows that overlay the current view, used to present critical information, request decisions, or guide users through specific tasks. The Meta Horizon OS UI Set⁠ provides several specialized dialog composables.

Shows both the dialog UI code and how the dialogs are rendered.

Common features

Modality: Typically block interaction with the underlying UI until dismissed.

Structure: Generally consist of a title, description/body content, and action buttons.

Theming: Background, text colors, and button styles are derived from SpatialTheme. Dialog backgrounds often use SpatialTheme.colorScheme.dialog.

Dismissal: Usually dismissed via action buttons (Primary, Secondary, Tertiary). Explicit dismiss actions might be needed depending on the context.

Dialog types

Basic dialog (`SpatialBasicDialog`)

The standard dialog format.

Usage: Confirmation prompts, simple alerts, presenting information with required actions.

Key Parameters:

title: String

description: String

primaryChoiceActionLabel: String, onPrimaryChoiceActionClick: () -> Unit (Required)

secondaryChoiceActionLabel: String?, onSecondaryChoiceActionClick: (() -> Unit)? (Optional, often “Cancel”)

tertiaryChoiceActionLabel: String?, onTertiaryChoiceActionClick: (() -> Unit)? (Optional, less common action)

thumbnail: @Composable (() -> Unit)?: Optional area at the top for an image or video preview.

steps: SpatialDialogSteps?: Optional indicator for multi-step dialogs. (data class SpatialDialogSteps(val current: Int, val total: Int))

import com.meta.spatial.uiset.dialog.SpatialBasicDialog
import androidx.compose.foundation.Image
import androidx.compose.ui.res.painterResource
// ... other imports

SpatialBasicDialog(
    title = "Discard Changes?",
    description = "Are you sure you want to discard all unsaved changes? This action cannot be undone.",
    primaryChoiceActionLabel = "Discard", // Often the destructive or confirming action
    onPrimaryChoiceActionClick = { /* Handle discard */ },
    secondaryChoiceActionLabel = "Cancel", // Often the safe action
    onSecondaryChoiceActionClick = { /* Dismiss dialog */ }
)

// With Thumbnail
SpatialBasicDialog(
    thumbnail = {
        Image(painterResource(R.drawable.sample_thumbnail), null) // Use your drawable
    },
    title = "Update Available",
    description = "A new version of the application is ready to install.",
    primaryChoiceActionLabel = "Install Now",
    onPrimaryChoiceActionClick = { /* Handle install */ },
    secondaryChoiceActionLabel = "Later",
    onSecondaryChoiceActionClick = { /* Dismiss */ }
)

Icon dialog (`SpatialIconDialog`)

Similar to SpatialBasicDialog, but includes a prominent icon above the title.

Usage: Alerts or confirmations where an icon adds significant context (for example, warning, success, error).

Key Parameters:

Same as SpatialBasicDialog, plus:

icon: @Composable () -> Unit: Composable function to render the icon.

import com.meta.spatial.uiset.dialog.SpatialIconDialog
import androidx.compose.material3.Icon
import com.meta.spatial.uiset.theme.icons.SpatialIcons
import com.meta.spatial.uiset.theme.icons.regular.Warning
import com.meta.spatial.uiset.theme.SpatialColor

SpatialIconDialog(
    icon = {
        Icon(
            SpatialIcons.Regular.Warning, "",
            tint = SpatialColor.y60, // Example custom color
            modifier = Modifier.size(40.dp)
        )
    },
    title = "Connection Lost",
    description = "Please check your internet connection and try again.",
    primaryChoiceActionLabel = "Retry",
    onPrimaryChoiceActionClick = { /* Handle retry */ },
    secondaryChoiceActionLabel = "OK",
    onSecondaryChoiceActionClick = { /* Dismiss */ }
)

Info dialog (`SpatialInfoDialog`)

Includes an additional “info banner” section at the bottom, typically used for disclaimers or secondary information.

Usage: Situations requiring legal notices, additional context, or warnings separate from the main description.

Key Parameters:

Same as SpatialBasicDialog, plus:

infoBannerIcon: @Composable () -> Unit: Icon for the info banner.

infoBannerText: String: Text content for the info banner.

import com.meta.spatial.uiset.dialog.SpatialInfoDialog
// ... other imports

SpatialInfoDialog(
    title = "Enable Feature X?",
    description = "Feature X requires access to your contacts to function.",
    infoBannerIcon = { Icon(SpatialIcons.Regular.Info, null) },
    infoBannerText = "Your contacts will only be used locally and not shared.",
    primaryChoiceActionLabel = "Allow",
    onPrimaryChoiceActionClick = { /* Handle allow */ },
    secondaryChoiceActionLabel = "Deny",
    onSecondaryChoiceActionClick = { /* Handle deny */ }
)

Choice list dialog (`SpatialChoiceListDialog`)

Presents a list of selectable items (typically using radio buttons for single selection) within the dialog body.

Usage: When the user needs to select one option from a predefined list as part of a workflow initiated by the dialog.

Key Parameters:

Same as SpatialBasicDialog, plus:

listHeaderText: String: Title for the list section.

items: List<SpatialChoiceListDialogItem>: The list of choices.

selectedItem: SpatialChoiceListDialogItem?: The currently selected item state (managed externally).

onItemSelected: (SpatialChoiceListDialogItem) -> Unit: Callback when an item is selected.

SpatialChoiceListDialogItem Data Class:

  data class SpatialChoiceListDialogItem(
      val leading: @Composable () -> Unit, // Often an Icon
      val title: String,
      val subtitle: String,
      val enabled: Boolean = true
  )

import com.meta.spatial.uiset.dialog.SpatialChoiceListDialog
import com.meta.spatial.uiset.dialog.foundation.SpatialChoiceListDialogItem
// ... other imports

var currentSelection by remember { mutableStateOf<SpatialChoiceListDialogItem?>(null) }
val choices = remember { listOf(
    SpatialChoiceListDialogItem(leading = { Icon(SpatialIcons.Regular.Wifi, null) }, title = "Network A", subtitle = "Connected"),
    SpatialChoiceListDialogItem(leading = { Icon(SpatialIcons.Regular.Wifi, null) }, title = "Network B", subtitle = "Available"),
    SpatialChoiceListDialogItem(leading = { Icon(SpatialIcons.Regular.WifiOff, null) }, title = "Network C", subtitle = "Out of range", enabled = false)
)}

SpatialChoiceListDialog(
    title = "Select Wi-Fi Network",
    description = "Choose a network to connect to.",
    listHeaderText = "Available Networks",
    items = choices,
    selectedItem = currentSelection,
    onItemSelected = { selected -> currentSelection = selected },
    primaryChoiceActionLabel = "Connect",
    onPrimaryChoiceActionClick = { /* Use currentSelection */ },
    secondaryChoiceActionLabel = "Cancel",
    onSecondaryChoiceActionClick = { /* Dismiss */ }
)

Choose the dialog type that best fits the information and actions required from the user. Use dialogs sparingly to avoid interrupting the user’s flow unnecessarily.

Did you find this page helpful?