O que é StateFlow em Kotlin?

Resposta rápida: StateFlow é um Flow quente da biblioteca kotlinx.coroutines que sempre guarda um valor atual. Quem começa a coletar recebe imediatamente esse estado e depois continua ouvindo as mudanças. Em apps Android e backends Kotlin, ele é o padrão mais comum para expor estado de tela, sessão, conexão ou configuração a partir de um ViewModel ou de um serviço de domínio — sem reinventar um bus de eventos.

Pense no StateFlow como o placar de um jogo: qualquer pessoa que olhe agora vê o placar atual; quem continuar olhando verá os próximos gols. Não é uma fila de “eventos que aconteceram enquanto você estava fora”; é o estado presente, sempre disponível.

CaracterísticaStateFlow
Tipo de fluxoQuente (hot)
Valor atualSempre existe (value)
Estado inicialObrigatório
DeduplicaçãoSuprime valores iguais consecutivos
ConcorrênciaThread-safe para leitura/escrita
Caso de uso típicoEstado de UI, sessão, feature flags

Sintaxe básica

import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update

data class UiState(
    val carregando: Boolean = false,
    val mensagem: String = "",
    val itens: List<String> = emptyList(),
)

class CatalogoViewModel {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    fun carregar() {
        _uiState.update { it.copy(carregando = true, mensagem = "") }
        // ... buscar dados ...
        _uiState.update {
            it.copy(
                carregando = false,
                itens = listOf("Coroutines", "StateFlow", "Compose"),
                mensagem = "Catálogo atualizado",
            )
        }
    }
}

A superfície pública expõe apenas StateFlow (somente leitura). A mutação fica no MutableStateFlow privado. Esse padrão evita que a UI reescreva o estado por acidente.

Ler e escrever o valor atual

val contador = MutableStateFlow(0)

println(contador.value) // 0

contador.value = 1
contador.update { atual -> atual + 1 }

println(contador.value) // 2
  • value lê ou substitui o estado atual.
  • update { } recebe o valor anterior e devolve o novo. Use quando a próxima versão depende da anterior.
  • compareAndSet(expect, update) troca o valor só se o atual ainda for o esperado — útil em algoritmos concorrentes mais explícitos.

Coletar o StateFlow

import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.flow.collect

suspend fun observar(uiState: StateFlow<UiState>) = coroutineScope {
    launch {
        uiState.collect { estado ->
            println("carregando=${estado.carregando} itens=${estado.itens.size}")
        }
    }
}

O primeiro valor entregue ao coletor é o estado já presente no StateFlow. Depois disso, só entram emissões em que o novo valor é diferente do anterior segundo equals.

No Jetpack Compose para Android:

@Composable
fun CatalogoScreen(viewModel: CatalogoViewModel) {
    val estado by viewModel.uiState.collectAsStateWithLifecycle()

    if (estado.carregando) {
        CircularProgressIndicator()
    } else {
        LazyColumn {
            items(estado.itens) { item -> Text(item) }
        }
    }
}

Se você ainda está montando a arquitetura da tela, o guia de MVVM com Kotlin e o tutorial de Flow mostram onde o StateFlow se encaixa entre repositório, ViewModel e UI.

StateFlow vs Flow frio vs SharedFlow vs Channel

NecessidadeEscolhaMotivo
Estado atual sempre disponível (UI, sessão)StateFlowtem value, exige inicial, deduplica iguais
Pipeline sob demanda (rede, disco, transformação)Flow friocada collect reinicia o trabalho
Eventos one-shot (navegação, snackbar, analytics)SharedFlow ou Channelnão exige estado atual; replay/buffer configuráveis
Broadcast com histórico curtoSharedFlow(replay = N)reenvia os últimos N eventos a novos coletores
Comunicação ponto a ponto entre coroutinesChannelfila com capacidade e backpressure explícitos
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.asSharedFlow

sealed interface EventoUi {
    data class MostrarSnackbar(val texto: String) : EventoUi
    data object NavegarParaDetalhe : EventoUi
}

class TelaViewModel {
    private val _estado = MutableStateFlow(UiState())
    val estado: StateFlow<UiState> = _estado.asStateFlow()

    private val _eventos = MutableSharedFlow<EventoUi>()
    val eventos = _eventos.asSharedFlow()

    suspend fun salvar() {
        _estado.update { it.copy(carregando = true) }
        // ... persistir ...
        _estado.update { it.copy(carregando = false, mensagem = "Salvo") }
        _eventos.emit(EventoUi.MostrarSnackbar("Alterações salvas"))
    }
}

Regra prática: estado que a tela precisa redesenhar → StateFlow. efeito que deve rodar uma vez → SharedFlow/Channel. Misturar os dois no mesmo fluxo costuma gerar snackbars duplicados ou estados “consumidos” demais.

Por que valores iguais não reaparecem?

StateFlow compara o novo valor com o atual via Any.equals. Se forem iguais, a emissão é descartada. Isso evita recomposições e coletas inúteis, mas surpreende quem tenta reenviar o mesmo evento:

data class Alerta(val id: Int, val texto: String)

val alerta = MutableStateFlow(Alerta(1, "Sem conexão"))

alerta.value = Alerta(1, "Sem conexão") // não notifica coletores
alerta.value = Alerta(2, "Sem conexão") // notifica: id mudou

Se a identidade do evento importa mais que o conteúdo, modele um tipo de evento separado (SharedFlow) em vez de forçar o StateFlow a mentir sobre o estado.

Concorrência, dispatchers e escopo

MutableStateFlow é seguro para atualização a partir de várias threads/coroutines. Ainda assim, o trabalho que produz o novo estado deve viver em um escopo claro — no Android, o viewModelScope; no backend, o escopo do request ou do serviço.

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class SessaoService {
    private val escopo = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    private val _logado = MutableStateFlow(false)
    val logado: StateFlow<Boolean> = _logado.asStateFlow()

    fun iniciarSessao(token: String) {
        escopo.launch {
            validarToken(token)
            _logado.value = true
        }
    }
}

Combine com o que você já sabe de coroutines, launch e dispatchers: o StateFlow guarda o resultado; a coroutine faz o trabalho.

Operadores úteis com StateFlow

Como StateFlow é um Flow, você pode mapear, filtrar e combinar — mas lembre que operadores intermediários devolvem um Flow comum, não outro StateFlow, a menos que você converta de novo com stateIn.

import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.flow.SharingStarted

class BuscaViewModel(
    private val escopo: CoroutineScope,
) {
    private val _consulta = MutableStateFlow("")
    val consulta: StateFlow<String> = _consulta.asStateFlow()

    val consultaNormalizada: StateFlow<String> = _consulta
        .map { it.trim().lowercase() }
        .stateIn(
            scope = escopo,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = "",
        )

    fun onConsultaChange(texto: String) {
        _consulta.value = texto
    }
}

stateIn é o caminho idiomático para transformar um fluxo frio (repositório, DataStore, WebSocket) em estado quente consumível pela UI. SharingStarted.WhileSubscribed evita manter coletores ativos quando ninguém está ouvindo.

StateFlow no backend Kotlin

Embora o exemplo clássico seja Android, o mesmo tipo resolve estado compartilhado em serviços JVM: feature flags em memória, status de circuit breaker, contagem de conexões WebSocket ou progresso de um job.

class ProgressoImportacao {
    private val _progresso = MutableStateFlow(0)
    val progresso: StateFlow<Int> = _progresso.asStateFlow()

    fun marcar(percentual: Int) {
        require(percentual in 0..100)
        _progresso.update { maxOf(it, percentual) }
    }
}

Endpoints SSE/WebSocket podem coletar progresso e empurrar atualizações para o cliente sem polling. Para pipelines de mensageria e APIs, o guia de Kotlin para backend cobre o restante da stack.

Erros comuns

  • Usar StateFlow para eventos one-shot. Snackbar, navegação e resultado de “salvar” não são estado persistente. Com StateFlow, um valor igual some e um coletor atrasado pode “ver” um evento velho como se fosse atual. Prefira SharedFlow ou Channel.
  • Expor MutableStateFlow na API pública. A UI passa a poder escrever no estado. Sempre publique StateFlow via asStateFlow() ou uma propriedade de tipo somente leitura.
  • Esquecer o valor inicial. MutableStateFlow exige um estado de partida. Modele um UiState vazio/carregando em vez de usar null sem necessidade.
  • Atualizar com value = value.copy(...) em corrida. Entre ler e escrever, outro coroutine pode ter mudado o estado. update { } aplica a transformação de forma atômica em relação ao valor observado.
  • Esperar reemissão de valores iguais. Se o teste ou a UI “não atualiza”, verifique se o novo objeto é equal ao anterior. Data classes iguais não disparam coleta.
  • Coletar sem respeitar o ciclo de vida no Android. collect direto numa coroutine desligada do Lifecycle pode atualizar UI morta ou vazar trabalho. Prefira collectAsStateWithLifecycle ou repeatOnLifecycle.
  • Transformar com map e esquecer stateIn. O resultado de map é um Flow frio: cada novo coletor recalcula. Para estado compartilhado, feche com stateIn.

Boas práticas

  • Modele o estado como uma data class imutável (UiState) e publique um único StateFlow, em vez de vários booleanos soltos.
  • Mantenha a mutação perto da regra de negócio (ViewModel/serviço) e deixe a UI só coletar e renderizar — o mesmo espírito do state no Compose.
  • Use update para mudanças derivadas; use atribuição a value só para substituições óbvias.
  • Separe estado (StateFlow) de efeito (SharedFlow/Channel).
  • Em testes, prefira Turbine ou runTest com coleta controlada — o post Testando Flow, StateFlow e Turbine mostra o setup completo.
  • Documente o estado inicial: ele é a primeira coisa que a UI enxerga e define o loading vazio vs. erro vs. conteúdo.

Perguntas frequentes

StateFlow substitui LiveData? Na prática, sim na maior parte dos apps Kotlin modernos. StateFlow é multiplataforma, integra com coroutines e não depende do Lifecycle Android no tipo em si. No Compose, a coleta com lifecycle fica na camada de UI.

Preciso de distinctUntilChanged com StateFlow? Não para o próprio StateFlow: a deduplicação já é embutida. Depois de um map, o Flow resultante volta a ser comum — aí distinctUntilChanged ou um novo stateIn podem ser necessários.

Qual a diferença para MutableState do Compose? mutableStateOf/State vivem no runtime do Compose e disparam recomposição. StateFlow vive em kotlinx.coroutines e serve ViewModel, domínio e backends sem depender de Compose. O glossário de State detalha a ponte entre os dois.

StateFlow tem buffer? Conceitualmente ele guarda só o valor atual. Coletores lentos não acumulam um histórico de estados intermediários: ao processar a próxima emissão, recebem o valor mais recente disponível após a deduplicação.

Posso resetar o StateFlow? Sim: atribua de novo o estado inicial (_uiState.value = UiState()) ou um valor sentinela explícito. Não existe “clear” especial — o estado atual é sempre algum valor.

Próximos passos

Termos relacionados

  • Flow — streams assíncronos frios dos quais o StateFlow herda a API de coleta
  • State — holder de estado do Compose e a relação com StateFlow
  • Coroutine — unidade de concorrência que produz e coleta o estado
  • Channel — fila para eventos e comunicação entre coroutines
  • ViewModel — dono típico do MutableStateFlow na camada de apresentação
  • Emit — operação de emitir valores em builders de Flow