repository·master·Indexed 20 days ago
https://github.com/canopas/compose-intro-showcaseAn Android library for Jetpack Compose that provides an introductory showcase and onboarding UI to highlight specific app features. It includes the IntroShowcase composable, the .introShowCaseTarget() modifier for designating sequence steps, and IntroShowcaseState for managing the walkthrough flow.
TapTargetView (which is intended for legacy views) but specifically tailored for the Jetpack Compose ecosystem.To create an onboarding or feature highlight flow, wrap your UI components within the IntroShowcase composable.
IntroShowcase manages the visibility of the showcase and provides a callback when the sequence is finished. Use the showIntroShowCase boolean to control when the intro starts and onShowCaseCompleted to handle the state change once the user has finished interacting with the highlights.
@Composable
fun ShowcaseSample() {
var showAppIntro by remember {
mutableStateOf(true)
}
IntroShowcase(
showIntroShowCase = showAppIntro,
dismissOnClickOutside = false,
onShowCaseCompleted = {
//App Intro finished!!
showAppIntro = false
},
) {
// Target components go here
}
}To use the Intro Showcase View library in your Android project, add the following dependency to your build.gradle file. The library is available on Maven Central.
implementation 'com.canopas.intro-showcase-view:introshowcaseview:2.0.1'Use the .introShowCaseTarget() modifier on any Composable to designate it as a step in the showcase sequence.
Key parameters for the modifier:
index: The order of this step in the showcase sequence (starting from 0).style: A ShowcaseStyle object (e.g., ShowcaseStyle.Default) used to customize the appearance of the highlight circle and background. You can use .copy() to override properties like backgroundColor, backgroundAlpha, and targetCircleColor.content: A composable lambda that defines the instructional text, icons, or UI elements shown to the user during this specific step.Note: The IntroShowcase wrapper also accepts backgroundColor and contentColor parameters to style the overlay.
FloatingActionButton(
onClick = {},
modifier = Modifier.introShowCaseTarget(
index = 0,
style = ShowcaseStyle.Default.copy(
backgroundColor = Color(0xFF1C0A00),
backgroundAlpha = 0.98f,
targetCircleColor = Color.White
),
content = {
Column {
Text(text = "Check emails", color = Color.White)
Text(text = "Click here to check/send emails", color = Color.White)
}
}
),
backgroundColor = ThemeColor,
contentColor = Color.White
) {
Icon(Icons.Filled.Email, contentDescription = "Email")
}The IntroShowcase Composable is the primary entrypoint for displaying a guided walkthrough. It wraps your existing UI content and overlays a ShowcasePopup when showIntroShowCase is true.
To use it:
showIntroShowCase boolean.onShowCaseCompleted to handle the end of the walkthrough.IntroShowcaseScope provided in the content lambda to attach targets to your UI elements.rememberIntroShowcaseState() to manage the lifecycle and current step of the showcase.IntroShowcase(
showIntroShowCase = isWalkthroughVisible,
onShowCaseCompleted = { isWalkthroughVisible = false },
state = rememberIntroShowcaseState(),
dismissOnClickOutside = true
) {
// Your existing UI content goes here
Button(
onClick = { /* ... */ },
modifier = Modifier.introShowCaseTarget(
index = 0,
style = ShowcaseStyle.Default
) {
// Content for the target scope
}
)
}To manage the state of your showcase flow, use the rememberIntroShowcaseState composable function. This creates an IntroShowcaseState instance that is remembered across recompositions.
Note that changing the initialIndex parameter after the initial composition will not recreate or update the existing state.
val showcaseState = rememberIntroShowcaseState(initialIndex = 0)The IntroShowcaseState class tracks the progress of the showcase. It maintains a map of targets and the index of the currently active target.
Key properties and methods:
currentTargetIndex: The index of the target currently being showcased.currentTarget: Returns the IntroShowcaseTargets object for the current index, or null if no target exists at that index.reset(): Resets the currentTargetIndex to 0, effectively restarting the showcase flow.// Accessing the current target
val target = showcaseState.currentTarget
// Restarting the showcase
showcaseState.reset()Use the ShowcaseWindow Composable to display an overlay content on top of your existing UI. It manages the lifecycle of a separate window, ensuring that the provided content is shown when the Composable enters the composition and is dismissed when it leaves. It automatically handles the connection to the parent's CompositionContext, LifecycleOwner, ViewModelStoreOwner, and SavedStateRegistryOwner to ensure Compose state and lifecycle-aware components work correctly within the overlay.
ShowcaseWindow {
// Your showcase UI content goes here
Text("This is an overlay!")
}Within the IntroShowcase content block, you can use the introShowCaseTarget extension function on Modifier to designate specific UI components as steps in the walkthrough.
Parameters:
index: The sequential order of the step in the showcase.style: The visual style of the highlight (defaults to ShowcaseStyle.Default).content: A @Composable BoxScope.() -> Unit block used to define the target's scope.Modifier.introShowCaseTarget(
index = 1,
style = ShowcaseStyle.Default
) {
// Target content
}