Reveal Documentation

Reveal is a library for creating coach marks, onboarding tutorials, and walkthrough effects in Compose Multiplatform for Android, iOS, Desktop, and Web.

Key Concepts

• Revealable: An element on the screen that is highlighted during the effect.
• Reveal area: The specific area around a Revealable that is highlighted (usually with slight padding).
• Overlay: The layer that greys out all content except for the Revealable area. It can also host explanatory items (like text or images).

Since the overlay is rendered in a popup attached to the window where Reveal is composed, you can use Reveal inside ModalBottomSheet or Dialog.

Crucial Requirement: The Reveal instance and its revealable items must be placed inside the sheet or dialog's content. A Reveal instance placed outside a sheet cannot reveal items inside it because they reside in different windows.

ModalBottomSheet(onDismissRequest = { /* ... */ }) {
    val revealState = rememberRevealState()

    Reveal(revealState = revealState) {
        // Sheet contents, revealable via Modifier.revealable(...)
    }
}

Add the reveal-core dependency to your project. The minimum supported Android SDK is 23 (Android 6.0).

Artifacts

• reveal-core: Contains the core classes required for using the library.
• reveal-shapes: Provides additional shapes for explanatory items in the overlay.

dependencies {
    implementation("com.svenjacobs.reveal:reveal-core:$REVEAL_VERSION")
}

In version 5.0, the rendering model for the reveal overlay has changed. Instead of being hoisted to a RevealCanvas at the top of the Compose hierarchy, Reveal now renders its overlay in a full-screen popup attached to the window it is composed in.

Key changes:

• RevealCanvas, RevealCanvasState, and rememberRevealCanvasState() have been removed.
• The reveal-compat-android artifact is no longer needed and should be removed.
• The revealCanvasState argument has been removed from the Reveal composable.
• The reveal effect now correctly renders above ModalBottomSheet and Dialog components, provided the Reveal composable is placed inside the sheet or dialog's content.

The reveal-compat-android artifact and its associated classes (FullscreenRevealOverlayInserter, InPlaceRevealOverlayInserter, RevealOverlayInserter) have been removed. If you were using FullscreenRevealOverlayInserter(revealableOffset = ...) to correct misplaced effects in legacy Android view hierarchies, this is no longer necessary as the offset is now measured automatically.

dependencies {
    // remove this line
    implementation("com.svenjacobs.reveal:reveal-compat-android:$REVEAL_VERSION")
}

To use Reveal, you need to manage a RevealState using rememberRevealState() and wrap your screen content in the Reveal composable.

Typically, you should have at most one Reveal instance per application screen. Because the overlay is rendered in a full-screen popup, Reveal can be placed anywhere in the Compose hierarchy.

@Composable
fun MainScreen() {
    val revealState = rememberRevealState()

    // Usually one instance per screen
    Reveal(
        revealState = revealState,
        onRevealableClick = { key -> /* Handle click on revealable area */ },
        onOverlayClick = { key -> /* Handle click on overlay */ },
    ) {
        // Your screen contents go here
    }
}

Because ModalBottomSheet and Dialog render into their own separate windows, a Reveal composable placed outside of them cannot reveal items inside them. To make Reveal work within these components, you must place the Reveal composable and its RevealState inside the sheet's or dialog's content area.

ModalBottomSheet(onDismissRequest = { /* ... */ }) {
    val revealState = rememberRevealState()

    Reveal(revealState = revealState) {
        // Sheet contents
    }
}

Because the overlay is now a popup attached to the window, it can render on top of modal components. To ensure the reveal effect works inside a ModalBottomSheet or Dialog, place the Reveal composable and its RevealState inside the content block of the modal component.

ModalBottomSheet(onDismissRequest = { /* ... */ }) {
    val revealState = rememberRevealState()

    Reveal(revealState = revealState) {
        // Sheet contents
    }
}

To make an element part of the reveal effect, apply the Modifier.revealable(key = ...) modifier to it. You can use any type for the key (e.g., an enum or String). To trigger the effect for a specific item, call revealState.reveal(key).

enum class Keys { HelloWorld }

// Inside your Reveal block:
Column {
    Text(
        modifier = Modifier.revealable(key = Keys.HelloWorld),
        text = "Hello world",
    )
}

// To launch the effect:
revealState.reveal(Keys.HelloWorld)