singleTop

singleTop is an Android activity launch mode that governs how new intents are delivered and how activity instances are reused within a task. When an activity is declared with launchMode="singleTop" and a new intent targets that activity, the system behavior depends on whether an instance of the activity already exists at the top of the current task’s back stack.

If the targeted activity is already at the top, the system does not create a new instance. Instead, it routes the new intent to the existing instance via the onNewIntent() callback. In this case, the activity can handle the updated intent without a full recreation. If the activity is not at the top, a new instance is created and pushed onto the back stack as in the standard launch mode.

Developers should override onNewIntent() to process the incoming intent when an existing top instance receives a new launch. They may also call setIntent(intent) within onNewIntent() to update the activity’s internal reference to the latest intent.

Use cases for singleTop include screens that should not have multiple copies, such as a chat interface, a media player, or a search results view that can receive new data without needing a new activity instance.

Relation to other launch modes: singleTop differs from the default standard mode, which always creates a new instance on each launch, and from singleTask or singleInstance, which reuse a single instance across different scenarios even if not at the top. Understanding these distinctions helps manage activity lifecycle, back stack behavior, and data handling in an Android app.

Implementation note: declare android:launchMode="singleTop" in the activity tag of the AndroidManifest.xml.