12k
All articles

Cómo añadir mapas nativos a una app de React Native

Configura expo-maps en React Native con Apple Maps y Google Maps, marcadores compartidos, permisos de ubicación, controles de cámara, clave de Android y límites de iOS.

OpenReplay Team
OpenReplay Team
Cómo añadir mapas nativos a una app de React Native

Instala expo-maps en una development build y, después, renderiza AppleMaps.View en iOS y GoogleMaps.View en Android. Ambos componentes reciben los mismos datos de cámara, marcadores y ubicación, por lo que un único wrapper cubre las dos plataformas.

La mayoría de los tutoriales de mapas para React Native están escritos para react-native-maps, y sus props no son compatibles con la librería de Expo. Si copias un fragmento de <MapView> en un proyecto con expo-maps, obtendrás errores de tipos en todo, incluida la cámara.

Esta guía cubre todo el flujo con expo-maps: elegir la librería, compilar la app, añadir la API key de Android, renderizar un mapa en ambas plataformas, añadir marcadores, centrar el mapa en el usuario y gestionar los toques sobre los marcadores. También aborda las limitaciones de versión de iOS que determinan qué funcionalidades puedes usar. Si prefieres los vector tiles y los estilos personalizados de Mapbox, consulta cómo crear un mapa en React Native con Mapbox.

Puntos clave

  • expo-maps muestra Apple Maps en iOS y Google Maps en Android mediante dos componentes, AppleMaps.View y GoogleMaps.View, y no admite Google Maps en iOS.
  • Ejecuta expo-maps en una development build. Apple Maps no necesita API key, pero Android requiere una clave de Google Maps en android.config.googleMaps.apiKey dentro de app.json, seguida de una recompilación.
  • cameraPosition solo define dónde arranca el mapa. Para mover la cámara después, llama a setCameraPosition a través de una ref al mapa.
  • La documentación de Expo indica iOS 17 como versión mínima para expo-maps, y los callbacks de toque en marcadores, como onMarkerClick, requieren iOS 18.

¿Deberías usar expo-maps o react-native-maps?

Para un proyecto de Expo que ya utiliza development builds, elige expo-maps. Elige react-native-maps si necesitas Google Maps en iOS o ejecutar la app dentro de Expo Go. expo-maps es la librería de mapas propia de Expo, y renderiza mediante SwiftUI en iOS y Jetpack Compose en Android. react-native-maps la mantiene la comunidad y ofrece una única API MapView que funciona con varios proveedores de mapas.

expo-mapsreact-native-maps
Desarrollada porEquipo de ExpoComunidad
Capa nativaSwiftUI (iOS), Jetpack Compose (Android)Un único componente MapView
Proveedor en iOSSolo Apple MapsApple Maps o Google Maps
Versión mínima de iOSiOS 17 según la documentación de Expo; el README del paquete indica iOS 18.0No se trata aquí
Expo GoUsa una development buildIncluida en Expo Go, según la documentación de Expo
Componentes de React como marcadoresNo compatible (se usan marcadores de imagen)Compatible
Estructura de la APIDos componentes por plataformaUn único componente

En su lanzamiento, el anuncio de expo-maps describía la librería como una versión alfa: «Con el SDK 53, lanzamos nuestra versión alfa de expo-maps». La página de referencia del SDK 58 no muestra ninguna etiqueta de estado. Consulta la referencia de expo-maps para conocer su estado actual antes de publicar. La página de react-native-maps de Expo cubre la otra opción.

Instalar expo-maps y crear una development build

expo-maps necesita dos cosas: el paquete y un binario nativo (una development build) que lo incluya. Instala el paquete con la Expo CLI para que la versión coincida con tu SDK:

npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios      # or: npx expo run:android

expo-location proporcionará más adelante en esta guía las coordenadas del usuario. expo-dev-client convierte el binario en una development build. La documentación de expo-maps solo describe su ejecución en una development build, así que utiliza una. También puedes compilar en la nube con EAS. Si quieres un proyecto listo para usar, npx create-expo-app --example with-maps arranca con expo-maps ya instalado y configurado.

Añadir la API key de Google Maps para Android

Apple Maps funciona sin clave. Google Maps en Android necesita una API key de Google Cloud con Maps SDK for Android habilitado, añadida a app.json, y una recompilación posterior de la app.

  1. Crea un proyecto de Google Cloud y habilita Maps SDK for Android.
  2. Crea una API key y restríngela a apps de Android usando el nombre de tu paquete y la huella SHA-1 de tu certificado de firma. En las compilaciones con EAS, eas credentials muestra la huella.
  3. Añade la clave y el plugin de permisos de ubicación a 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"
        }
      ]
    ]
  }
}
  1. Recompila con npx expo run:android. Una recarga de JavaScript no aplica los cambios en la configuración nativa.

En las opciones del plugin, requestLocationPermission es un booleano que añade los permisos a AndroidManifest.xml y a Info.plist, y locationPermission define el mensaje de uso, exclusivo de iOS. app.json no puede leer variables de entorno. Para mantener la clave fuera del control de versiones, traslada la misma ruta android.config.googleMaps.apiKey a app.config.js y lee la clave desde process.env.

Mostrar un mapa en ambas plataformas

expo-maps no incluye un componente multiplataforma, así que escribe un pequeño wrapper que elija AppleMaps.View o GoogleMaps.View según Platform.OS y pase a ambos la misma cameraPosition. Un CameraPosition es un objeto con coordinates y 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>;
}

La última rama gestiona la web y cualquier otra plataforma en la que no exista ninguno de los dos componentes.

Añadir marcadores a partir de un único array de datos

Tanto AppleMaps.View como GoogleMaps.View reciben un array markers, y ambos tipos de marcador aceptan id, title y coordinates. Esto significa que una única función de mapeo puede alimentar las dos plataformas. Añade los campos específicos de cada plataforma, como tintColor en Apple o snippet en Google, aplicando el spread sobre el marcador compartido:

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' }))}

expo-maps no puede renderizar componentes de React como marcadores. Para pines personalizados, admite iconos de imagen cargados con useImage de expo-image.

¿Cómo mostrar la ubicación del usuario y centrar el mapa en ella?

Mostrar la ubicación del usuario en expo-maps requiere tres pasos: solicitar el permiso de ubicación, mostrar el punto de ubicación una vez concedido el permiso y mover la cámara cuando lleguen las coordenadas. El permiso debe declararse en la compilación y solicitarse en tiempo de ejecución antes de que pueda aparecer el punto. El hook useLocationPermissions de expo-maps devuelve el estado actual y una función para solicitarlo.

TareaAppleMaps.ViewGoogleMaps.View
Punto de ubicaciónproperties.isMyLocationEnabledproperties.isMyLocationEnabled más userLocation
Seguir al usuarioLlamar a setCameraPositionuserLocation.followUserLocation
Duración de la animaciónNo compatibleduration en ms

Activa el punto solo después de que se haya concedido el permiso. Un issue reportado en Android mostró que activar isMyLocationEnabled sin el permiso provocaba el cierre de la app en Android, mientras que iOS lo ignoraba. El 4 de noviembre de 2026 se fusionó una corrección en la rama principal de Expo, pero las versiones anteriores de expo-maps no la incluyen, y condicionar el punto al permiso funciona en todas las versiones. El issue también señala que la opción requestLocationPermission del config plugin solo declara los permisos en tiempo de compilación y nunca solicita nada en tiempo de ejecución.

En expo-maps, la prop cameraPosition está documentada como la posición inicial de la cámara del mapa, por lo que modificarla a través del estado no es la forma documentada de mover la cámara. En su lugar, llama a setCameraPosition a través de una ref. En iOS no se admite la duración de la animación, y la promesa devuelta se resuelve cuando se programa la actualización de la cámara, no cuando termina su animación.

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>
  );
}

Location.getCurrentPositionAsync proporciona las coordenadas. En Android, followUserLocation mantiene la cámara sobre el usuario, por lo que el código solo llama a setCameraPosition en iOS. Si el permiso se deniega de forma definitiva, el mapa se queda en START y aparece debajo un mensaje no bloqueante.

Responder a los toques en marcadores con onMarkerClick

Para gestionar los toques en marcadores con expo-maps, pasa onMarkerClick a AppleMaps.View o a GoogleMaps.View. El callback recibe el marcador tocado, de modo que puedes leer su id y buscar el registro correspondiente en tus datos. En Android funciona en todas las versiones compatibles. En iOS, la documentación de Expo lo marca como iOS 18.0+, y el mismo límite se aplica al resto de callbacks de toque y a la selección programática con selectMarker y selectAnnotation.

En dispositivos con iOS 17 el mapa se sigue renderizando, pero tocar un marcador no produce ningún efecto en JavaScript. Si la interfaz depende de los toques, establece ios.deploymentTarget en 18.0 mediante expo-build-properties. De lo contrario, añade una lista debajo del mapa que controle el mismo estado de selección, para que los usuarios de iOS 17 puedan seguir accediendo a cada lugar.

Conclusión

expo-maps cubre la pantalla de mapa habitual con componentes nativos: Apple Maps en iOS, Google Maps en Android, un único array de datos compartido y una breve bifurcación con Platform.OS. Como siguiente paso, recompila con tu clave de Android y prueba en un dispositivo real con iOS 17 y en otro con iOS 18. Es ahí donde se manifiestan las diferencias en los toques y los permisos. Tras la publicación, el session replay para React Native muestra los fallos que no aparecen en los logs, como usuarios que desplazan el mapa buscando un pin o que descartan la solicitud de ubicación. Ver esas sesiones te permite saber si el flujo del mapa funciona para usuarios reales.

Preguntas frecuentes

¿Por qué el mapa de Google funciona en desarrollo pero aparece en blanco en la build de Play Store?

Normalmente, la API key está restringida a una huella SHA-1 incorrecta. Con Play App Signing, Google vuelve a firmar la versión de lanzamiento, por lo que la app instalada lleva el certificado de firma de apps de Google en lugar de tu clave de subida o de depuración. Copia el SHA-1 de firma de apps desde la página Integridad de la app en Play Console y añádelo a las restricciones de apps de Android de la clave. Mantén también en la clave tu huella de desarrollo.

¿Puede expo-maps dibujar rutas, áreas o círculos de radio?

Sí. Tanto AppleMaps.View como GoogleMaps.View aceptan las props polylines, polygons y circles. Cada prop recibe un array de formas construidas a partir de coordenadas, y un círculo recibe un centro y un radio en metros. expo-maps dibuja formas, pero no calcula rutas. Para un trayecto en coche o a pie, obtén la geometría de la ruta de un servicio de direcciones y pasa las coordenadas decodificadas como una polyline.

¿Cómo cambio expo-maps a la vista de satélite?

Establece mapType dentro de la prop properties. En AppleMaps.View, usa el enum AppleMapsMapType: STANDARD, IMAGERY (solo satélite) o HYBRID (satélite con carreteras y etiquetas). En GoogleMaps.View, usa GoogleMapsMapType: NORMAL, SATELLITE, HYBRID o TERRAIN. Los nombres de los valores difieren según la plataforma, por lo que un wrapper compartido debería mapear un único ajuste, como 'satellite', a IMAGERY en iOS y a SATELLITE en Android.

¿El permiso de ubicación concedido a través de expo-maps también sirve para expo-location?

Sí. Android e iOS conceden el acceso a la ubicación a la app en su conjunto, no a una librería concreta. Una vez que el usuario acepta la solicitud en primer plano del hook useLocationPermissions de expo-maps, expo-location ve el mismo permiso, de modo que getCurrentPositionAsync se ejecuta sin una segunda solicitud. La ubicación en segundo plano es un permiso independiente en ambas plataformas y requiere su propia solicitud a través de expo-location.

DevTools for the frontend

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

We use cookies to improve your experience. By using our site, you accept cookies.