Expo UI (@expo/ui)

Quando Usar

Use esta funcionalidade quando precisar criar interfaces de usuário nativas com o pacote @expo/ui: SwiftUI real no iOS e Jetpack Compose no Android renderizados a partir do React em um aplicativo Expo ou React Native. Abrange componentes universais multiplataforma (Host, Column, Row, Button, Text, List e mais importados de @expo/ui), substituições diretas...

@expo/ui renderiza interfaces de usuário nativas reais a partir do React: SwiftUI no iOS, Jetpack Compose no Android. Comece com seus componentes universais (uma árvore para iOS, Android e web) e desça para SwiftUI/Jetpack Compose específico da plataforma apenas quando a camada universal não for suficiente. Ele também oferece substituições diretas para migrar de bibliotecas de UI da comunidade RN.

Estas instruções acompanham o SDK mais recente do Expo. A camada universal requer SDK 56+. Substituições diretas e as camadas específicas da plataforma também existem no SDK 55. Para detalhes de componentes em um SDK específico, consulte a documentação do Expo UI para essa versão.

Instalação

npx expo install @expo/ui

No SDK 56, @expo/ui funciona no Expo Go, então npx expo start o executa diretamente — nenhuma compilação personalizada é necessária. Em SDKs mais antigos, compile um cliente de desenvolvimento primeiro (npx expo run:ios / npx expo run:android).

Toda árvore @expo/ui — universal ou específica da plataforma — deve ser envolvida em Host.

Escolhendo uma abordagem (leia isto primeiro)

Percorra esta lista e pare na primeira camada que atender à necessidade:

1. Componentes universais — comece aqui. Importe da raiz @expo/ui. Uma árvore de componentes é executada sem modificações no iOS, Android e web a partir de uma única fonte (Compose no Android, SwiftUI no iOS, react-native-web/react-dom na web). Sem divisões de arquivos de plataforma. → ./references/universal.md

2. Específico da plataforma (SwiftUI / Jetpack Compose). Importe de @expo/ui/swift-ui ou @expo/ui/jetpack-compose. Use apenas quando a camada universal não tiver um componente ou modificador que você precisa, ou quando precisar de comportamento ou otimização específica da plataforma. Desvantagem: você escreve duas árvores e as divide em arquivos .ios.tsx / .android.tsx (ou ramifica em Platform.OS) — mais código para manter.

   @expo/ui/swift-ui é apenas para iOS. @expo/ui/jetpack-compose é apenas para Android. Importar qualquer um deles em um arquivo que roda na outra plataforma causará falha em tempo de execução com erros "Unable to get view config". Isole árvores específicas da plataforma em arquivos .ios.tsx / .android.tsx colocados em components/ (nunca dentro de app/ — Expo Router não suporta extensões de plataforma para arquivos de rota), ou proteja com Platform.OS em um arquivo de rota regular. Host deve sempre ser importado de @expo/ui (a raiz do pacote universal), não dos subpacotes específicos da plataforma. → ./references/swift-ui.md e ./references/jetpack-compose.md

Já usa uma biblioteca de UI da comunidade RN? @expo/ui também oferece substituições diretas — trocas compatíveis com API para bibliotecas populares (@gorhom/bottom-sheet, @react-native-community/datetimepicker e mais), importadas de @expo/ui/community/<name>. Este é um caminho lateral de migração para substituir uma dependência existente, não uma etapa na decisão universal vs. plataforma acima. → ./references/drop-in-replacements.md

Referências

Consulte estes recursos conforme necessário:

references/
  universal.md             Universal @expo/ui components and when to use them (SDK 56+)
  drop-in-replacements.md  API-compatible replacements for RN community UI libraries
  swift-ui.md              Platform-specific iOS UI: @expo/ui/swift-ui components, modifiers, RNHostView, useNativeState
  jetpack-compose.md       Platform-specific Android UI: @expo/ui/jetpack-compose components, modifiers, LazyColumn caveat, icons, useNativeState

Limitações

• Use esta funcionalidade apenas quando a tarefa corresponder claramente ao escopo do produto ou API upstream.
• Verifique comandos, comportamento da API, preços, cotas, credenciais e efeitos de implantação contra a documentação oficial atual antes de fazer alterações.
• Não trate exemplos gerados como substitutos para testes específicos do ambiente, revisão de segurança ou aprovação do usuário para ações destrutivas ou custosas.