Adicionando mapas nativos a um app React Native
Configure o expo-maps no React Native com Apple Maps e Google Maps, marcadores compartilhados, permissões de localização, câmera, chave Android e limites do iOS.
Instale o expo-maps em um development build e, em seguida, renderize AppleMaps.View no iOS e GoogleMaps.View no Android. Os dois componentes recebem os mesmos dados de câmera, marcadores e localização, então um único wrapper atende às duas plataformas.
A maioria dos tutoriais de mapas para React Native é escrita para o react-native-maps, e as props usadas neles não funcionam na biblioteca da Expo. Se você copiar um trecho com <MapView> para um projeto com expo-maps, vai receber erros de tipo em tudo, inclusive na câmera.
Este guia cobre o fluxo completo no expo-maps: escolher a biblioteca, gerar o build do app, adicionar a chave de API do Android, renderizar um mapa nas duas plataformas, adicionar marcadores, centralizar o mapa no usuário e tratar toques em marcadores. Também aborda os limites de versão do iOS que determinam quais recursos você pode usar. Se você prefere tiles vetoriais e estilos personalizados do Mapbox, veja como criar um mapa em React Native com Mapbox.
Principais pontos
- O expo-maps exibe o Apple Maps no iOS e o Google Maps no Android por meio de dois componentes,
AppleMaps.VieweGoogleMaps.View, e não oferece suporte ao Google Maps no iOS. - Execute o expo-maps em um development build. O Apple Maps não precisa de chave de API, mas o Android exige uma chave do Google Maps em
android.config.googleMaps.apiKeyno app.json, seguida de um novo build. cameraPositiondefine apenas a posição inicial do mapa. Para mover a câmera depois, chamesetCameraPositionem uma ref do mapa.- A documentação da Expo indica o iOS 17 como versão mínima para o expo-maps, e callbacks de toque em marcadores, como
onMarkerClick, exigem o iOS 18.
Você deve usar expo-maps ou react-native-maps?
Para um projeto Expo que já usa development builds, escolha o expo-maps. Escolha o react-native-maps se você precisar do Google Maps no iOS ou de rodar o app no Expo Go. O expo-maps é a biblioteca de mapas da própria Expo e renderiza por meio de SwiftUI no iOS e Jetpack Compose no Android. O react-native-maps é mantido pela comunidade e oferece uma única API MapView que funciona com vários provedores de mapas.
| expo-maps | react-native-maps | |
|---|---|---|
| Desenvolvido por | Equipe da Expo | Comunidade |
| Camada nativa | SwiftUI (iOS), Jetpack Compose (Android) | Um componente MapView |
| Provedor no iOS | Somente Apple Maps | Apple Maps ou Google Maps |
| Versão mínima do iOS | iOS 17, segundo a documentação da Expo; o README do pacote indica iOS 18.0 | Não abordado aqui |
| Expo Go | Use um development build | Incluído no Expo Go, segundo a documentação da Expo |
| Componentes React como marcadores | Não suportado (use marcadores com imagem) | Suportado |
| Formato da API | Dois componentes por plataforma | Um componente |
No lançamento, o anúncio do expo-maps descrevia a biblioteca como alfa: “Com o SDK 53, estamos lançando nossa versão alfa do expo-maps.” A página de referência do SDK 58 não exibe nenhum rótulo de status. Consulte a referência do expo-maps para verificar o status atual antes de ir para produção. A página do react-native-maps na documentação da Expo cobre a outra opção.
Instale o expo-maps e crie um development build
O expo-maps precisa de duas coisas: o pacote e um binário nativo (um development build) que o inclua. Instale o pacote com a Expo CLI para que a versão seja compatível com o seu SDK:
npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios # or: npx expo run:android
O expo-location fornece as coordenadas do usuário mais adiante neste guia. O expo-dev-client transforma o binário em um development build. A documentação do expo-maps descreve apenas a execução em um development build, então use um. Você também pode gerar o build na nuvem com o EAS. Para um projeto pronto, npx create-expo-app --example with-maps já vem com o expo-maps instalado e configurado.
Adicione a chave de API do Google Maps para Android
O Apple Maps funciona sem chave. Já o Google Maps no Android precisa de uma chave de API do Google Cloud com o Maps SDK for Android ativado, adicionada ao app.json, seguida de um novo build do app.
- Crie um projeto no Google Cloud e ative o Maps SDK for Android.
- Crie uma chave de API e restrinja-a a apps Android usando o nome do seu pacote e a impressão digital SHA-1 do seu certificado de assinatura. Para builds com EAS, o comando
eas credentialsexibe a impressão digital. - Adicione a chave e o plugin de permissão de localização ao app.json:
{
"expo": {
"android": {
"package": "com.example.places",
"config": {
"googleMaps": { "apiKey": "YOUR_ANDROID_MAPS_KEY" }
}
},
"plugins": [
[
"expo-maps",
{
"requestLocationPermission": true,
"locationPermission": "Allow $(PRODUCT_NAME) to show your position on the map"
}
]
]
}
}
- Gere um novo build com
npx expo run:android. Um reload do JavaScript não aplica alterações na configuração nativa.
Nas opções do plugin, requestLocationPermission é um booleano que adiciona as permissões ao AndroidManifest.xml e ao Info.plist, e locationPermission define a mensagem de uso, exclusiva do iOS. O app.json não consegue ler variáveis de ambiente. Para manter a chave fora do controle de versão, mova o mesmo caminho android.config.googleMaps.apiKey para o app.config.js e leia a chave a partir de process.env nesse arquivo.
Exiba um mapa nas duas plataformas
O expo-maps não tem um componente multiplataforma, então escreva um pequeno wrapper que escolha AppleMaps.View ou GoogleMaps.View com base em Platform.OS e passe o mesmo cameraPosition para os dois. Um CameraPosition é um objeto com coordinates e zoom:
import { Platform, Text } from 'react-native';
import { AppleMaps, GoogleMaps } from 'expo-maps';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
export function BasicMap() {
if (Platform.OS === 'ios') return <AppleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
if (Platform.OS === 'android') return <GoogleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
return <Text>Maps are only available on Android and iOS.</Text>;
}
O último branch trata a web e qualquer outra plataforma, onde nenhum dos dois componentes existe.
Adicione marcadores a partir de um único array de dados
Tanto AppleMaps.View quanto GoogleMaps.View recebem um array markers, e os dois tipos de marcador aceitam id, title e coordinates. Isso significa que uma única função de mapeamento pode alimentar as duas plataformas. Adicione campos exclusivos de cada plataforma, como tintColor na Apple ou snippet no Google, usando spread sobre o marcador compartilhado:
type Place = { id: string; title: string; latitude: number; longitude: number };
export const PLACES: Place[] = [
{ id: 'office', title: 'Office', latitude: 51.5154, longitude: -0.141 },
{ id: 'cafe', title: 'Cafe', latitude: 51.5113, longitude: -0.1198 },
];
export const toMarker = (p: Place) => ({
id: p.id,
title: p.title,
coordinates: { latitude: p.latitude, longitude: p.longitude },
});
// iOS: markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
// Android: markers={PLACES.map((p) => ({ ...toMarker(p), snippet: 'Open now' }))}
O expo-maps não consegue renderizar componentes React como marcadores. Para pins personalizados, ele oferece suporte a ícones de imagem carregados com useImage do expo-image.
Como exibir a localização do usuário e centralizar o mapa nela?
Exibir a localização do usuário no expo-maps envolve três etapas: solicitar a permissão de localização, mostrar o ponto de localização depois que a permissão for concedida e mover a câmera quando as coordenadas chegarem. A permissão precisa ser declarada no build e solicitada em tempo de execução antes que o ponto possa aparecer. O hook useLocationPermissions do expo-maps retorna o status atual e uma função para solicitá-la.
| Tarefa | AppleMaps.View | GoogleMaps.View |
|---|---|---|
| Ponto de localização | properties.isMyLocationEnabled | properties.isMyLocationEnabled mais userLocation |
| Seguir o usuário | Chamar setCameraPosition | userLocation.followUserLocation |
| Duração da animação | Não suportado | duration em ms |
Só ative o ponto depois que a permissão for concedida. Uma issue reportada no Android mostrou que ativar isMyLocationEnabled sem a permissão fazia o app travar no Android, enquanto o iOS simplesmente ignorava. Uma correção foi incorporada ao branch principal da Expo em 4 de novembro de 2026, mas as versões mais antigas do expo-maps não a incluem, e condicionar o ponto à permissão funciona em todas as versões. A issue também destaca que a opção requestLocationPermission do config plugin apenas declara as permissões em tempo de build e nunca solicita nada em tempo de execução.
No expo-maps, a prop cameraPosition é documentada como a posição inicial da câmera do mapa, então alterá-la via state não é a forma documentada de mover a câmera. Em vez disso, chame setCameraPosition em uma ref. No iOS, a duração da animação não é suportada, e a promise retornada é resolvida quando a atualização da câmera é agendada, e não quando a animação termina.
import { useEffect, useRef, useState, type ComponentRef } from 'react';
import { Platform, Text, View } from 'react-native';
import { AppleMaps, GoogleMaps, useLocationPermissions } from 'expo-maps';
import * as Location from 'expo-location';
import { PLACES, toMarker } from './places';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
type Coords = { latitude: number; longitude: number };
export function PlacesMap({ onSelect }: { onSelect: (id: string) => void }) {
const appleRef = useRef<ComponentRef<typeof AppleMaps.View>>(null);
const [permission, requestPermission] = useLocationPermissions();
const [me, setMe] = useState<Coords | null>(null);
const granted = !!permission?.granted;
useEffect(() => {
if (permission && !permission.granted && permission.canAskAgain) requestPermission();
}, [permission]);
useEffect(() => {
if (!granted) return;
Location.getCurrentPositionAsync().then(({ coords }) => {
const here = { latitude: coords.latitude, longitude: coords.longitude };
setMe(here);
appleRef.current?.setCameraPosition({ coordinates: here, zoom: 14 }); // iOS only; no duration
});
}, [granted]);
const handleMarker = (m: { id?: string }) => m.id && onSelect(m.id);
const denied = permission && !permission.granted && !permission.canAskAgain;
const map =
Platform.OS === 'ios' ? (
<AppleMaps.View
ref={appleRef}
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
properties={{ isMyLocationEnabled: granted }}
onMarkerClick={handleMarker} // iOS 18+
/>
) : Platform.OS === 'android' ? (
<GoogleMaps.View
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map(toMarker)}
properties={{ isMyLocationEnabled: granted }}
userLocation={me ? { coordinates: me, followUserLocation: true } : undefined}
onMarkerClick={handleMarker}
/>
) : (
<Text>Maps are only available on Android and iOS.</Text>
);
return (
<View style={{ flex: 1 }}>
{map}
{denied && <Text>Location is off. Enable it in Settings to see where you are.</Text>}
</View>
);
}
O Location.getCurrentPositionAsync fornece as coordenadas. No Android, followUserLocation mantém a câmera no usuário, então o código só chama setCameraPosition no iOS. Se a permissão for negada definitivamente, o mapa permanece em START e uma mensagem não bloqueante aparece abaixo dele.
Responda a toques em marcadores com onMarkerClick
Para tratar toques em marcadores no expo-maps, passe onMarkerClick para AppleMaps.View ou GoogleMaps.View. O callback recebe o marcador tocado, então você pode ler o id dele e encontrar o registro correspondente nos seus dados. No Android, isso funciona em todas as versões suportadas. No iOS, a documentação da Expo indica iOS 18.0+, e o mesmo limite se aplica aos demais callbacks de toque e à seleção programática com selectMarker e selectAnnotation.
Em dispositivos com iOS 17, o mapa continua sendo renderizado, mas tocar em um marcador não dispara nada no JavaScript. Se a interface baseada em toques for obrigatória, defina ios.deploymentTarget como 18.0 via expo-build-properties. Caso contrário, adicione uma lista abaixo do mapa que controle o mesmo estado de seleção, para que usuários do iOS 17 ainda consigam acessar cada local.
Conclusão
O expo-maps atende à tela de mapa mais comum com componentes nativos: Apple Maps no iOS, Google Maps no Android, um único array de dados compartilhado e um pequeno branch com Platform.OS. Em seguida, gere um novo build com sua chave do Android e teste em um dispositivo real com iOS 17 e em outro com iOS 18. É ali que as diferenças de toque e de permissão aparecem. Depois do lançamento, o session replay para React Native mostra as falhas que você não enxerga nos logs, como usuários arrastando o mapa à procura de um pin ou dispensando o pedido de localização. Assistir a essas sessões revela se o fluxo do mapa funciona para usuários reais.
Perguntas frequentes
Por que o mapa do Google funciona em desenvolvimento, mas fica em branco no build da Play Store?
Geralmente, a chave de API está restrita à impressão digital SHA-1 errada. Com a Assinatura de apps do Google Play, o Google assina novamente a versão de release, então o app instalado carrega o certificado de assinatura de apps do Google em vez da sua chave de upload ou de debug. Copie o SHA-1 do certificado de assinatura de apps na página Integridade do app do Play Console e adicione-o às restrições de app Android da chave. Mantenha também a impressão digital de desenvolvimento na chave.
O expo-maps consegue desenhar rotas, áreas ou círculos de raio?
Sim. Tanto AppleMaps.View quanto GoogleMaps.View aceitam as props polylines, polygons e circles. Cada prop recebe um array de formas construídas a partir de coordenadas, e um círculo recebe um centro e um raio em metros. O expo-maps desenha formas, mas não calcula rotas. Para um trajeto de carro ou a pé, obtenha a geometria da rota de um serviço de direções e passe as coordenadas decodificadas como uma polyline.
Como mudo o expo-maps para a visualização de satélite?
Defina mapType dentro da prop properties. No AppleMaps.View, use o enum AppleMapsMapType: STANDARD, IMAGERY (somente satélite) ou HYBRID (satélite com ruas e rótulos). No GoogleMaps.View, use GoogleMapsMapType: NORMAL, SATELLITE, HYBRID ou TERRAIN. Os nomes dos valores variam conforme a plataforma, então um wrapper compartilhado deve mapear uma única configuração, como 'satellite', para IMAGERY no iOS e SATELLITE no Android.
A permissão de localização concedida pelo expo-maps também vale para o expo-location?
Sim. O Android e o iOS concedem acesso à localização ao app como um todo, e não a uma biblioteca específica. Depois que o usuário aceita o pedido de localização em primeiro plano feito pelo hook useLocationPermissions do expo-maps, o expo-location enxerga a mesma permissão, então getCurrentPositionAsync é executado sem um segundo pedido. A localização em segundo plano é uma concessão separada nas duas plataformas e precisa de uma solicitação própria via expo-location.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k