---
title: "StateFlow em Kotlin: O que É e Como Funciona | Kotlin Brasil"
url: "https://kotlin.dev.br/glossario/stateflow/"
markdown_url: "https://kotlin.dev.br/glossario/stateflow.MD"
description: "O que é StateFlow em Kotlin, com exemplos: MutableStateFlow, value, update, collect, diferença para SharedFlow e Flow frio, e uso com ViewModel e Compose."
date: "2026-11-20"
author: "Karina Melo"
---

# StateFlow em Kotlin: O que É e Como Funciona | Kotlin Brasil

O que é StateFlow em Kotlin, com exemplos: MutableStateFlow, value, update, collect, diferença para SharedFlow e Flow frio, e uso com ViewModel e Compose.


## O que é StateFlow em Kotlin?

**Resposta rápida:** `StateFlow` é um [Flow](/glossario/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](/glossario/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

```kotlin
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

```kotlin
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

```kotlin
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:

```kotlin
@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](/guias/guia-arquitetura-mvvm-kotlin/) e o [tutorial de Flow](/tutoriais/kotlin-flow-tutorial/) 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](/glossario/flow/) frio | cada collect reinicia o trabalho |
| Eventos one-shot (navegação, snackbar, analytics) | `SharedFlow` ou [Channel](/glossario/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 |

```kotlin
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:

```kotlin
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.

```kotlin
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](/glossario/coroutine/), [launch](/glossario/launch/) e [dispatchers](/glossario/dispatcher/): 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`.

```kotlin
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.

```kotlin
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](/guias/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](/glossario/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](/blog/testando-flow-stateflow-turbine-kotlin-2026/) 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](/glossario/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](/glossario/flow/) — entenda o fluxo frio por trás de operadores e builders
- [Guia completo de Kotlin Flow](/guias/kotlin-flow-guia/) — operators, cancelamento e padrões de produção
- [Tutorial de Flow](/tutoriais/kotlin-flow-tutorial/) — prática guiada com exemplos progressivos
- [State no Jetpack Compose](/glossario/state/) — `mutableStateOf`, hoisting e coleta na UI
- [Arquitetura MVVM com Kotlin](/guias/guia-arquitetura-mvvm-kotlin/) — onde o StateFlow se encaixa no app
- [Testando Flow e StateFlow com Turbine](/blog/testando-flow-stateflow-turbine-kotlin-2026/) — testes determinísticos de estado

### Termos relacionados

- [Flow](/glossario/flow/) — streams assíncronos frios dos quais o StateFlow herda a API de coleta
- [State](/glossario/state/) — holder de estado do Compose e a relação com StateFlow
- [Coroutine](/glossario/coroutine/) — unidade de concorrência que produz e coleta o estado
- [Channel](/glossario/channel/) — fila para eventos e comunicação entre coroutines
- [ViewModel](/glossario/viewmodel/) — dono típico do MutableStateFlow na camada de apresentação
- [Emit](/glossario/emit/) — operação de emitir valores em builders de Flow
