--- title: "Compose BOM no Android com Kotlin: versões compatíveis em 2026" url: "https://kotlin.dev.br/blog/compose-bom-android-kotlin-guia-2026/" markdown_url: "https://kotlin.dev.br/blog/compose-bom-android-kotlin-guia-2026.MD" description: "Aprenda a usar o Compose BOM no Android com Kotlin: Gradle, version catalog, bibliotecas compatíveis, atualização, testes e solução de conflitos de versão." date: "2026-08-08" author: "Karina Melo" --- # Compose BOM no Android com Kotlin: versões compatíveis em 2026 Aprenda a usar o Compose BOM no Android com Kotlin: Gradle, version catalog, bibliotecas compatíveis, atualização, testes e solução de conflitos de versão. **Resposta rápida:** o **Compose BOM** (Bill of Materials) é a forma recomendada de manter as bibliotecas do Jetpack Compose em versões compatíveis. Você declara uma versão do artefato `androidx.compose:compose-bom`, importa essa plataforma no Gradle e remove a versão individual de dependências como `ui`, `foundation`, `material3` e `ui-tooling-preview`. O BOM não adiciona bibliotecas sozinho, não controla o Kotlin nem o Android Gradle Plugin e não significa que todos os componentes tenham o mesmo número de versão. Em projetos reais, use também `platform()` nas dependências de teste, centralize o BOM no version catalog e valide cada atualização com build, testes e uma tela crítica do app. Quem abre um projeto Compose pela primeira vez costuma encontrar várias versões: Kotlin, Android Gradle Plugin, Compose Compiler, Material 3, Navigation, Lifecycle e as bibliotecas principais de UI. Tentar alinhar tudo manualmente gera uma combinação frágil, especialmente quando um módulo recebe uma atualização e outro continua preso a uma versão antiga. O **Compose BOM** reduz justamente essa parte do problema. Este guia explica como configurar o artefato no `build.gradle.kts`, como usá-lo com `libs.versions.toml`, o que ele cobre, o que fica de fora e como corrigir erros comuns de resolução. Se você ainda está estruturando a primeira interface, combine a leitura com o [guia de Jetpack Compose](/guias/guia-jetpack-compose/) e o tutorial de [layouts com Compose](/tutoriais/jetpack-compose-layouts/). ## O que é Compose BOM? BOM significa **Bill of Materials**. No ecossistema Gradle, um BOM é uma plataforma que publica restrições de versões para um conjunto de artefatos relacionados. Em vez de escolher manualmente uma versão para cada biblioteca Compose, o projeto importa uma tabela de compatibilidade mantida pelo AndroidX. Sem BOM, uma configuração poderia ficar assim: ```kotlin dependencies { implementation("androidx.compose.ui:ui:") implementation("androidx.compose.foundation:foundation:") implementation("androidx.compose.material3:material3:") debugImplementation("androidx.compose.ui:ui-tooling:") } ``` O problema não é apenas a repetição. Essas quatro versões podem ter sido publicadas em momentos diferentes e não formar uma combinação validada. Com o BOM, a configuração passa a declarar a plataforma uma vez: ```kotlin dependencies { val composeBom = platform( "androidx.compose:compose-bom:" ) implementation(composeBom) implementation("androidx.compose.ui:ui") implementation("androidx.compose.foundation:foundation") implementation("androidx.compose.material3:material3") implementation("androidx.compose.ui:ui-tooling-preview") debugImplementation("androidx.compose.ui:ui-tooling") } ``` As dependências continuam explícitas. O BOM fornece as versões compatíveis, mas você ainda escolhe quais bibliotecas entram no app. ## Qual versão do Compose BOM devo usar? Use a **versão estável mais recente publicada na documentação oficial do Android Developers ou no repositório Google Maven**, desde que ela seja compatível com o restante do projeto e passe pela sua validação. Evite copiar um número encontrado em um snippet antigo, resposta de fórum ou artigo sem verificar a data. As versões do Compose BOM usam um identificador baseado no calendário, como `AAAA.MM.00`. Isso não quer dizer que cada biblioteca Compose terá aquele mesmo número. O BOM pode apontar, por exemplo, para uma versão de `ui`, outra de `material3` e outra de um artefato auxiliar. Uma política segura de atualização: 1. consulte a versão estável atual do BOM; 2. altere somente a versão da plataforma no pull request; 3. rode `dependencies` ou `dependencyInsight` para conferir o que mudou; 4. compile todos os módulos Compose; 5. execute testes unitários, de UI e screenshots relevantes; 6. teste uma build release em aparelho ou emulador representativo; 7. registre regressões visuais ou de comportamento antes do merge. Não atualize automaticamente apenas porque apareceu um número novo. O BOM melhora a compatibilidade entre bibliotecas, mas não garante que seu código esteja livre de APIs descontinuadas ou mudanças visuais. ## Configuração recomendada no Gradle Kotlin DSL Em um módulo Android com Compose habilitado, a parte essencial fica assim: ```kotlin android { buildFeatures { compose = true } } dependencies { val composeBom = platform( "androidx.compose:compose-bom:" ) implementation(composeBom) androidTestImplementation(composeBom) implementation("androidx.activity:activity-compose:") implementation("androidx.compose.ui:ui") implementation("androidx.compose.ui:ui-tooling-preview") implementation("androidx.compose.foundation:foundation") implementation("androidx.compose.material3:material3") androidTestImplementation("androidx.compose.ui:ui-test-junit4") debugImplementation("androidx.compose.ui:ui-tooling") debugImplementation("androidx.compose.ui:ui-test-manifest") } ``` Observe três detalhes: - `implementation(composeBom)` aplica as restrições ao código principal; - `androidTestImplementation(composeBom)` aplica o mesmo alinhamento aos testes instrumentados; - `activity-compose` mantém sua própria versão porque não é necessariamente gerenciado pelo Compose BOM. Esquecer a plataforma em `androidTestImplementation` é uma causa comum de versões diferentes entre o app e os testes. O projeto compila no source set principal, mas falha ao resolver `ui-test-junit4` ou apresenta comportamento estranho no pipeline. ## Compose BOM com version catalog Em projetos com vários módulos, centralize o identificador no arquivo `gradle/libs.versions.toml`. ```toml [versions] compose-bom = "" activity-compose = "" [libraries] androidx-compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose-bom" } androidx-compose-ui = { module = "androidx.compose.ui:ui" } androidx-compose-ui-tooling = { module = "androidx.compose.ui:ui-tooling" } androidx-compose-ui-tooling-preview = { module = "androidx.compose.ui:ui-tooling-preview" } androidx-compose-ui-test-junit4 = { module = "androidx.compose.ui:ui-test-junit4" } androidx-compose-ui-test-manifest = { module = "androidx.compose.ui:ui-test-manifest" } androidx-compose-foundation = { module = "androidx.compose.foundation:foundation" } androidx-compose-material3 = { module = "androidx.compose.material3:material3" } androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "activity-compose" } ``` No `build.gradle.kts` do módulo: ```kotlin dependencies { implementation(platform(libs.androidx.compose.bom)) androidTestImplementation(platform(libs.androidx.compose.bom)) implementation(libs.androidx.activity.compose) implementation(libs.androidx.compose.ui) implementation(libs.androidx.compose.foundation) implementation(libs.androidx.compose.material3) implementation(libs.androidx.compose.ui.tooling.preview) androidTestImplementation(libs.androidx.compose.ui.test.junit4) debugImplementation(libs.androidx.compose.ui.tooling) debugImplementation(libs.androidx.compose.ui.test.manifest) } ``` Não coloque uma versão individual nas entradas `androidx-compose-ui`, `foundation` ou `material3` se a intenção é deixar o BOM controlá-las. Uma versão explícita pode sobrepor ou competir com a restrição da plataforma, escondendo o desalinhamento que você queria eliminar. ## platform ou enforcedPlatform? Na maioria dos apps, comece com `platform()`: ```kotlin implementation(platform(libs.androidx.compose.bom)) ``` Essa forma importa as recomendações e permite que a resolução do Gradle considere outras restrições. Já `enforcedPlatform()` força as versões da plataforma sobre dependências transitivas: ```kotlin implementation(enforcedPlatform(libs.androidx.compose.bom)) ``` `enforcedPlatform()` pode ser útil para diagnosticar ou impedir que uma biblioteca transitiva altere o conjunto Compose, mas também aumenta o risco de impor versões a consumidores de uma library. Em módulos publicados para terceiros, essa força pode vazar para o grafo de quem usa seu artefato. Regra prática: - app final: `platform()` normalmente basta; - library interna: prefira restrições previsíveis e teste o grafo do app; - library pública: evite impor agressivamente versões ao consumidor; - conflito real: use `dependencyInsight` antes de trocar para `enforcedPlatform()`. ## O que o Compose BOM cobre? O BOM cobre artefatos do conjunto Jetpack Compose incluídos em seu mapeamento, como partes de: - Compose UI; - Foundation; - Material e Material 3; - runtime; - animação; - tooling; - testes de UI. A lista exata pode evoluir. Consulte o mapeamento oficial da versão escolhida em vez de assumir que qualquer dependência com “compose” no nome faz parte do BOM. ## O que o Compose BOM não controla? Este é o ponto mais importante do guia. O Compose BOM **não é o BOM de todo o Android**. Normalmente ficam fora dele: - Kotlin e K2; - Android Gradle Plugin (AGP); - Gradle; - Java/JDK; - `compileSdk`, `minSdk` e `targetSdk`; - `activity-compose`; - Lifecycle e `lifecycle-runtime-compose`; - Navigation Compose; - Hilt e `hilt-navigation-compose`; - Coil; - Room; - Paging; - Accompanist; - Compose Multiplatform da JetBrains; - plugins de Compose Compiler quando exigidos pela combinação de Kotlin usada. Por isso, este código não é suficiente para atualizar o projeto inteiro: ```kotlin implementation(platform("androidx.compose:compose-bom:...")) ``` Você ainda precisa manter uma matriz coerente para Kotlin, AGP, plugin de Compose, SDK e bibliotecas AndroidX externas ao BOM. Para a arquitetura ao redor da UI, veja o [guia de MVVM com Kotlin e Compose](/guias/guia-arquitetura-mvvm-kotlin/) e a estratégia de [modularização Android](/blog/modularizacao-android-kotlin-compose-2026/). ## Compose Compiler e Kotlin Em projetos modernos, a integração do Compose Compiler acompanha a evolução do Kotlin e dos plugins de build. O erro comum é imaginar que atualizar o BOM também atualiza o compilador. Não atualiza. Se a build apresentar mensagem de incompatibilidade entre Kotlin e Compose Compiler, revise: 1. a versão do Kotlin aplicada pelos plugins; 2. a configuração recomendada para Compose no Kotlin usado pelo projeto; 3. o Android Gradle Plugin e o JDK exigidos; 4. plugins aplicados em módulos Android e multiplataforma; 5. configurações antigas de `composeOptions` que podem ter ficado no projeto após uma migração. Não resolva esse erro escolhendo aleatoriamente um número de BOM. O BOM trata bibliotecas em runtime e compile classpath; o compilador participa de outra camada do toolchain. ## Como descobrir qual versão foi resolvida O Gradle oferece relatórios melhores do que procurar no cache manualmente. Para listar dependências do módulo: ```bash ./gradlew :app:dependencies \ --configuration debugRuntimeClasspath ``` Para investigar um artefato específico: ```bash ./gradlew :app:dependencyInsight \ --configuration debugRuntimeClasspath \ --dependency androidx.compose.ui:ui ``` O `dependencyInsight` mostra: - versão solicitada; - versão selecionada; - restrição que participou da escolha; - dependência que trouxe o artefato; - motivo de conflito ou substituição. Rode também na configuração de testes quando o erro estiver no `connectedAndroidTest`: ```bash ./gradlew :app:dependencyInsight \ --configuration debugAndroidTestRuntimeClasspath \ --dependency androidx.compose.ui:ui-test-junit4 ``` Em um projeto multimódulo, troque `:app` pelo módulo que realmente declara Compose. O grafo de uma feature pode divergir do app se o BOM não foi importado naquele módulo. ## Projetos multimódulo: onde declarar o BOM? Cada módulo que declara diretamente bibliotecas Compose deve receber a plataforma em seu bloco de dependências, a menos que a organização use uma convenção Gradle centralizada para aplicá-la. Evite copiar e colar dezenas de blocos. Um **convention plugin** pode encapsular: - `buildFeatures.compose = true`; - importação do Compose BOM; - dependências básicas de UI e tooling; - opções de lint; - configuração de testes Compose. Mesmo com plugin de convenção, mantenha as features explícitas: um módulo não precisa receber Material 3 se só usa runtime ou Foundation. A plataforma deve ser compartilhada; o conjunto de bibliotecas pode variar. Em times grandes, inclua uma verificação no CI para impedir versões explícitas em artefatos gerenciados pelo BOM. Isso evita que um módulo novo copie um snippet antigo e crie um segundo eixo de atualização. ## Posso usar uma versão diferente de uma biblioteca? Tecnicamente, sim. Você pode declarar uma versão explícita: ```kotlin implementation("androidx.compose.material3:material3:") ``` Mas faça isso como exceção documentada. Antes, responda: - qual bug ou API exige o override? - a versão foi testada com o restante do conjunto? - quando o override será removido? - o BOM seguinte já inclui a versão desejada? - há risco de incompatibilidade binária ou visual? Um override temporário pode ser válido para testar uma correção. Vários overrides permanentes anulam o principal benefício do BOM. ## Erros comuns e como corrigir ### “Could not find androidx.compose:compose-bom” Confirme se o projeto inclui o repositório Google: ```kotlin dependencyResolutionManagement { repositories { google() mavenCentral() } } ``` Também verifique se a versão existe de fato. Um identificador copiado de uma previsão, issue ou consulta sem release publicada não será resolvido. ### Dependência Compose sem versão continua falhando O módulo pode não ter importado a plataforma na configuração correta. Confira se `implementation(platform(...))` aparece no mesmo módulo e source set da biblioteca sem versão. ### Teste instrumentado resolve outra versão Adicione: ```kotlin androidTestImplementation(platform(libs.androidx.compose.bom)) ``` Depois, inspecione `debugAndroidTestRuntimeClasspath`. ### Material 3 não recebe a versão esperada Verifique se existe um pin explícito no version catalog, em um convention plugin ou numa dependência transitiva. Use `dependencyInsight` em vez de adivinhar. ### Atualizei o BOM e o compilador quebrou Provavelmente a causa está no Kotlin, plugin Compose, AGP ou JDK — não no alinhamento do runtime. Leia a mensagem completa e revise a matriz do toolchain. ### Preview do Android Studio parou de funcionar Confirme `ui-tooling-preview` em `implementation` e `ui-tooling` em `debugImplementation`. Depois, teste sync, build da variante debug e compatibilidade do Android Studio com o projeto. ## Compose BOM, bibliotecas alpha e previews Uma versão estável do BOM prioriza um conjunto estável. Se você precisa experimentar uma API alpha, pode ser necessário usar um BOM específico de preview ou declarar uma exceção. Trate esse caminho como experimental: - isole em branch ou módulo; - não promova para produção sem avaliar mudanças de API; - fixe a combinação usada no experimento; - acompanhe release notes; - remova overrides quando a API chegar ao canal estável. Não misture versões alpha aleatórias num app crítico e espere que o BOM estável valide a combinação. Compatibilidade de resolução não é garantia de estabilidade de API. ## Testando uma atualização do Compose BOM Uma atualização responsável não termina no `./gradlew assembleDebug`. Use uma pirâmide de validação: ### 1. Resolução e compilação ```bash ./gradlew clean :app:assembleDebug :app:assembleRelease ``` ### 2. Testes unitários ```bash ./gradlew test ``` ### 3. Testes de UI Compose Execute os testes instrumentados que cobrem navegação, estado, acessibilidade e componentes críticos. O guia de [testes Android com Compose e Maestro](/guias/testes-android-compose-maestro/) ajuda a separar testes de componente e fluxos ponta a ponta. ### 4. Screenshot tests Mudanças em Material 3, tipografia, shapes ou componentes podem alterar pixels sem quebrar a compilação. Use a estratégia de [testes de screenshot em Compose](/blog/testes-screenshot-compose-kotlin-2026/) nas telas mais sensíveis. ### 5. Performance Se a atualização toca runtime, lazy layouts ou animações usadas intensamente, compare métricas com [Baseline Profiles e Macrobenchmark](/blog/baseline-profiles-macrobenchmark-android-kotlin-2026/). ### 6. Acessibilidade e dispositivo real Valide fonte ampliada, TalkBack, modo escuro, navegação por teclado quando aplicável e pelo menos um aparelho intermediário. Uma atualização visual pode passar por todos os testes automatizados e ainda cortar texto em português. ## Checklist para pull request Antes de aprovar uma mudança de BOM: - [ ] a versão existe no Google Maven e está documentada; - [ ] o BOM está centralizado no version catalog; - [ ] não há versões explícitas desnecessárias em artefatos gerenciados; - [ ] `implementation` e `androidTestImplementation` importam a plataforma; - [ ] módulos Compose usam a mesma política; - [ ] `dependencyInsight` não revela overrides inesperados; - [ ] debug e release compilam; - [ ] testes unitários e instrumentados passam; - [ ] screenshots críticas foram revisadas; - [ ] Kotlin, plugin Compose, AGP e JDK foram avaliados separadamente; - [ ] release notes relevantes foram lidas; - [ ] o rollback consiste em reverter uma única versão central. ## Perguntas frequentes ### O Compose BOM instala o Jetpack Compose? Não. Ele apenas fornece restrições de versões compatíveis. Você ainda precisa declarar `ui`, `foundation`, `material3`, tooling, testes e outras bibliotecas usadas. ### Posso remover todas as versões das dependências AndroidX? Não. Remova versões somente dos artefatos cobertos pelo BOM. Activity, Lifecycle, Navigation, Hilt, Room, Coil e outras bibliotecas mantêm versões próprias, salvo quando outro mecanismo de plataforma as gerencia. ### O Compose BOM controla o Compose Compiler? Não. Kotlin e a integração do compilador Compose pertencem ao toolchain de build. Atualizar o BOM não corrige automaticamente incompatibilidade de compilador. ### Preciso usar o BOM nos testes? Sim, quando os testes declaram bibliotecas Compose. Importe a plataforma em `androidTestImplementation` para alinhar `ui-test-junit4` e os demais artefatos. ### `platform()` ou `enforcedPlatform()`? Comece com `platform()`. Use `enforcedPlatform()` apenas quando você entende o conflito e quer forçar as restrições, especialmente com cuidado em libraries consumidas por outros projetos. ### O número do BOM é a versão do Material 3? Não. O número identifica a publicação do BOM. Cada biblioteca mapeada pode ter sua própria versão. ### Compose Multiplatform usa o mesmo BOM? Não trate os dois ecossistemas como equivalentes. Compose Multiplatform possui plugins, targets e ciclo de versões próprios. Consulte a configuração específica do projeto multiplataforma no guia de [Compose Multiplatform para Android, iOS e desktop](/blog/kotlin-compose-multiplatform-ui-2026/). ## Conclusão O Compose BOM resolve um problema específico e valioso: **alinhar as versões das bibliotecas Jetpack Compose que fazem parte de seu mapeamento**. A configuração recomendada é simples — importar `platform(androidx.compose:compose-bom)` e declarar os artefatos Compose sem versões individuais —, mas a operação madura exige mais: version catalog, plataforma também nos testes, auditoria com `dependencyInsight` e validação visual após atualizações. Use o BOM como uma fonte central de compatibilidade, não como atalho para ignorar o restante do toolchain. Kotlin, Compose Compiler, AGP, JDK, Activity, Lifecycle e Navigation ainda precisam de gestão própria. Quando essa separação fica clara, atualizar Compose deixa de ser uma sequência de tentativas e vira um pull request pequeno, observável e reversível. Para continuar, conecte esta configuração ao [guia de Jetpack Compose](/guias/guia-jetpack-compose/), à [arquitetura MVVM com Compose](/guias/guia-arquitetura-mvvm-kotlin/), aos [testes de screenshot](/blog/testes-screenshot-compose-kotlin-2026/), ao guia de [performance com Baseline Profiles](/blog/baseline-profiles-macrobenchmark-android-kotlin-2026/) e ao player de vídeo/áudio com [Media3 ExoPlayer em Compose](/blog/media3-exoplayer-compose-kotlin-2026/) (Media3 não entra no Compose BOM — declare a versão `androidx.media3` à parte, como Activity e Room). Assim, a plataforma de versões passa a fazer parte de uma rotina completa de qualidade Android — e não apenas de um snippet no Gradle.