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ística | StateFlow |
|---|---|
| Tipo de fluxo | Quente (hot) |
| Valor atual | Sempre existe (value) |
| Estado inicial | Obrigatório |
| Deduplicação | Suprime valores iguais consecutivos |
| Concorrência | Thread-safe para leitura/escrita |
| Caso de uso típico | Estado 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
valuelê 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
| Necessidade | Escolha | Motivo |
|---|---|---|
| Estado atual sempre disponível (UI, sessão) | StateFlow | tem value, exige inicial, deduplica iguais |
| Pipeline sob demanda (rede, disco, transformação) | Flow frio | cada collect reinicia o trabalho |
| Eventos one-shot (navegação, snackbar, analytics) | SharedFlow ou Channel | não exige estado atual; replay/buffer configuráveis |
| Broadcast com histórico curto | SharedFlow(replay = N) | reenvia os últimos N eventos a novos coletores |
| Comunicação ponto a ponto entre coroutines | Channel | fila 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. PrefiraSharedFlowouChannel. - Expor
MutableStateFlowna API pública. A UI passa a poder escrever no estado. Sempre publiqueStateFlowviaasStateFlow()ou uma propriedade de tipo somente leitura. - Esquecer o valor inicial.
MutableStateFlowexige um estado de partida. Modele umUiStatevazio/carregando em vez de usarnullsem 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.
collectdireto numa coroutine desligada do Lifecycle pode atualizar UI morta ou vazar trabalho. PrefiracollectAsStateWithLifecycleourepeatOnLifecycle. - Transformar com
mape esquecerstateIn. O resultado demapé um Flow frio: cada novo coletor recalcula. Para estado compartilhado, feche comstateIn.
Boas práticas
- Modele o estado como uma data class imutável (
UiState) e publique um únicoStateFlow, 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
updatepara mudanças derivadas; use atribuição avaluesó para substituições óbvias. - Separe estado (
StateFlow) de efeito (SharedFlow/Channel). - Em testes, prefira Turbine ou
runTestcom 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
- Flow em Kotlin — entenda o fluxo frio por trás de operadores e builders
- Guia completo de Kotlin Flow — operators, cancelamento e padrões de produção
- Tutorial de Flow — prática guiada com exemplos progressivos
- State no Jetpack Compose —
mutableStateOf, hoisting e coleta na UI - Arquitetura MVVM com Kotlin — onde o StateFlow se encaixa no app
- Testando Flow e StateFlow com Turbine — testes determinísticos de estado
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