SharedFlow: What It Is, SharedFlow vs StateFlow in Android

What is SharedFlow in Kotlin?

SharedFlow is a hot flow from the kotlinx.coroutines.flow library, which, unlike StateFlow, is not tied to a single state and can emit an arbitrary number of events to arbitrary subscribers. SharedFlow is the base type for StateFlow — StateFlow is actually implemented via SharedFlow with replay = 1.

The key feature of SharedFlow is that it does not have to store the last value. By default (replay = 0), a new subscriber receives nothing until a new event is sent. This makes SharedFlow ideal for scenarios where an event should be processed exactly once: navigation, Snackbar, system notifications, QR code scan results.

SharedFlow was stabilized in kotlinx.coroutines 1.4.0 (November 2020) along with StateFlow. According to the Kotlin Coroutines documentation (2025), SharedFlow uses fine-grained locking for subscriber synchronization and provides linear scalability up to 1000+ concurrent subscribers without performance degradation, confirmed by JetBrains tests.

SharedFlow vs StateFlow: When to Use What

The choice between SharedFlow and StateFlow depends on the semantics of the data being transferred: state (StateFlow) or event (SharedFlow). Below are clear criteria with examples.

The simplest rule: if the data should be shown on screen rotation — it's state (StateFlow). If on screen rotation the event should not repeat — it's a one-shot event (SharedFlow). For example, a toast with an error message is SharedFlow: on rotation the toast should not appear again. A product list is StateFlow: on rotation the list should remain on screen.

At IT Sectr we use SharedFlow for: navigation commands (screen transition, deep link opening), UI events (Snackbar, AlertDialog), system notifications (background data updates, payment result), analytics events (logging, tracking).

MutableSharedFlow: emit, tryEmit and Buffering

MutableSharedFlow is the mutable version of SharedFlow with emit() (suspend) and tryEmit() (non-suspend) methods for sending events. emit() suspends if the buffer is full and onBufferOverflow = SUSPEND. tryEmit() returns a Boolean indicating whether the event was successfully added to the buffer.

class EventBus {
    private val _events = MutableSharedFlow<UiEvent>(
        replay = 0,
        extraBufferCapacity = 10,
        onBufferOverflow = BufferOverflow.DROP_OLDEST
    )
    val events: SharedFlow<UiEvent> get() = _events

    suspend fun sendEvent(event: UiEvent) {
        _events.emit(event)
    }

    fun trySendEvent(event: UiEvent): Boolean {
        return _events.tryEmit(event)
    }
}

sealed interface UiEvent {
    data class ShowSnackbar(val message: String) : UiEvent
    data class NavigateTo(val route: String) : UiEvent
    data class ShowDialog(val title: String, val message: String) : UiEvent
}

Constructor parameters are critically important: replay = 0 ensures the event does not repeat for a new subscriber; extraBufferCapacity = 10 provides a buffer for rapid event emission before the UI subscribes; DROP_OLDEST is the overflow strategy: old events are dropped, new ones are preserved. According to Kotlin Coroutines Performance (JetBrains, 2024), SharedFlow with extraBufferCapacity = 64 processes over 100,000 events per second without loss.

SharedFlow for One-Shot Events: The Event Pattern

Event Pattern (or UiEvent) is Google's recommended way to pass one-shot events from ViewModel to View. Unlike state (StateFlow), an event should be processed exactly once, and on screen rotation it should not repeat. SharedFlow with replay = 0 is ideal for this task.

class CheckoutViewModel : ViewModel() {
    private val _uiState = MutableStateFlow<CheckoutState>(CheckoutState.Idle)
    val uiState: StateFlow<CheckoutState> get() = _uiState

    private val _event = MutableSharedFlow<CheckoutEvent>()
    val event: SharedFlow<CheckoutEvent> get() = _event

    fun placeOrder() {
        viewModelScope.launch {
            _uiState.value = CheckoutState.Loading
            try {
                val orderId = orderRepository.createOrder(cart)
                _uiState.value = CheckoutState.Success(orderId)
                _event.emit(CheckoutEvent.NavigateToOrderTracking(orderId))
            } catch (e: Exception) {
                _uiState.value = CheckoutState.Error(e.message)
                _event.emit(CheckoutEvent.ShowErrorSnackbar(e.message ?: "Layout error"))
            }
        }
    }
}

sealed interface CheckoutEvent {
    data class NavigateToOrderTracking(val orderId: String) : CheckoutEvent
    data class ShowErrorSnackbar(val message: String) : CheckoutEvent
}

In the View (Activity/Fragment): subscription to events should be done in lifecycleScope with repeatOnLifecycle(STATE.STARTED). On each entry into STARTED, the subscription is recreated, but the event does not repeat because SharedFlow with replay=0 has already released it. This ensures that navigation to the order tracking screen happens only once, not on every rotation.

SharedFlow Parameters: replay, extraBufferCapacity, onBufferOverflow

The MutableSharedFlow constructor accepts three parameters that determine buffer behavior. Incorrect configuration can lead to event loss or emit() blocking.

// Configurations for different scenarios:

// 1. One-shot UI events (navigation, toasts)
val uiEvents = MutableSharedFlow<UiEvent>(
    replay = 0,
    extraBufferCapacity = 5,
    onBufferOverflow = BufferOverflow.DROP_OLDEST
)

// 2. Replay flow for state synchronization (like StateFlow)
val stateLike = MutableSharedFlow<AppState>(
    replay = 1,
    extraBufferCapacity = 0
)

// 3. High-frequency event emission (analytics, logs)
val analytics = MutableSharedFlow<AnalyticsEvent>(
    replay = 0,
    extraBufferCapacity = 100,
    onBufferOverflow = BufferOverflow.DROP_OLDEST
)

Important: extraBufferCapacity + replay = total buffer size. If emit() is called faster than the subscriber processes events, the buffer fills up and onBufferOverflow triggers. For UI events, DROP_OLDEST is a safe strategy: old events (no longer relevant navigations) are dropped in favor of fresh ones. For financial transactions, use SUSPEND — this guarantees that no event is lost at the cost of blocking the sender.

Code Examples: SharedFlow in Kotlin

Example 1: SharedFlow for Navigation with Jetpack Navigation

Navigation commands are a classic use case for SharedFlow. A Fragment subscribes to events and performs navigation. On screen rotation, the command does not repeat.

// ViewModel
class AuthViewModel : ViewModel() {
    private val _navEvent = MutableSharedFlow<NavEvent>()
    val navEvent: SharedFlow<NavEvent> get() = _navEvent

    fun onLoginSuccess() {
        viewModelScope.launch {
            _navEvent.emit(NavEvent.NavigateTo(NavRoutes.HOME))
        }
    }

    fun onLogout() {
        viewModelScope.launch {
            _navEvent.emit(NavEvent.NavigateTo(NavRoutes.LOGIN))
        }
    }
}

sealed interface NavEvent {
    data class NavigateTo(val route: String) : NavEvent
    data class NavigateBack(val popUpTo: String? = null) : NavEvent
}

// In Fragment:
viewLifecycleOwner.lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.navEvent.collect { navEvent ->
            when (navEvent) {
                is NavEvent.NavigateTo -> findNavController().navigate(navEvent.route)
                is NavEvent.NavigateBack -> findNavController().popBackStack()
            }
        }
    }
}

Example 2: SharedFlow with Room and Flow Operators

A complex scenario: SharedFlow for background event notifications combined with StateFlow for the UI.

class NotificationViewModel : ViewModel() {
    private val _toastMessage = MutableSharedFlow<String>()
    val toastMessage: SharedFlow<String> get() = _toastMessage

    private val _notifications = MutableStateFlow<List<Notification>>(emptyList())
    val notifications: StateFlow<List<Notification>> get() = _notifications

    init {
        viewModelScope.launch {
            notificationChannel
                .consumeAsFlow()
                .collect { notification ->
                    _notifications.value = _notifications.value + notification
                    _toastMessage.emit("New notification: ${notification.title}")
                }
        }
    }

    fun dismissNotification(id: String) {
        _notifications.value = _notifications.value.filter { it.id != id }
    }

    fun markAllRead() {
        viewModelScope.launch {
            _notifications.value = _notifications.value.map { it.copy(isRead = true) }
            _toastMessage.emit("All notifications marked as read")
        }
    }
}

In this example: StateFlow stores the notification list (state — preserved on rotation), SharedFlow emits toast messages (one-shot events — not repeated on rotation). The combination of two Flow types is Google's recommended pattern for ViewModel starting from 2022.