A React wrapper for Apple's MapKit JS, providing a seamless way to integrate Apple Maps into your React applications.
npm install @1amageek/mapkitA React wrapper for Apple's MapKit JS, providing a seamless way to integrate Apple Maps into your React applications.
- πΊοΈ Full TypeScript support
- π React component lifecycle integration
- π Support for markers, custom annotations, and overlays
- π¨ Customizable map styling and controls
- π Automatic token management and refresh
- π― Built-in error handling
- π« Smooth animations and transitions
- π±οΈ Comprehensive event handling for map interactions, annotations, and user location
``bash`
npm install @1amageek/mapkit
You'll need:
1. An Apple Developer account
2. A Maps ID from the Apple Developer portal
3. A token generation endpoint in your backend
First, wrap your application with the MapKitProvider:
`tsx
import { MapKitProvider } from '@1amageek/mapkit';
const App = () => {
const fetchToken = async () => {
// Fetch your MapKit JS token from your server
const response = await fetch('your-token-endpoint');
const data = await response.json();
return {
token: data.token,
expiresAt: data.expiresAt // Unix timestamp in seconds
};
};
return (
options={{
language: 'en'
}}
>
);
};
`
Then use the Map component:
`tsx`
import { Map, MarkerAnnotation } from '@1amageek/mapkit';
The library supports a wide range of events for the map, annotations, and user location:
component emits various events related to map display and interaction:
- onRegionChangeStart: Triggered when the map region starts changing.
- onRegionChangeEnd: Triggered when the map region finishes changing.
- onRotationStart: Triggered when the map starts rotating.
- onRotationEnd: Triggered when the map finishes rotating.
- onScrollStart: Triggered when the map starts scrolling.
- onScrollEnd: Triggered when the map finishes scrolling.
- onZoomStart: Triggered when the map starts zooming.
- onZoomEnd: Triggered when the map finishes zooming.
- onMapTypeChange: Triggered when the map type changes (e.g., from satellite to standard).
- onSingleTap: Triggered when the map is tapped once.
- onDoubleTap: Triggered when the map is double-tapped.
- onLongPress: Triggered when the map is long-pressed.$3
-
onSelect: Triggered when an annotation is selected
- onDeselect: Triggered when an annotation is deselected
- onDrag: Triggered while an annotation is being dragged, providing real-time updates.
- onDragStart: Triggered when starting to drag an annotation
- onDragEnd: Triggered when finishing dragging an annotation$3
- onUserLocationChange: Triggered when the user's location changes. Provides the new coordinate and timestamp.
- onUserLocationError: Triggered when an error occurs while trying to retrieve the user's location.Example usage with events:
`tsx
import { Map, MarkerAnnotation } from '@1amageek/mapkit';const MapComponent = () => {
return (
id="my-map"
options={{
showsUserLocation: true,
showsCompass: "Adaptive",
}}
onRegionChangeStart={(event: mapkit.EventBase) => {
console.log("Region change start", event);
}}
onRegionChangeEnd={(event: mapkit.EventBase) => {
console.log("Region change end", event);
}}
region={{
center: {
latitude: 35.6812,
longitude: 139.7671
},
span: {
latitudeDelta: 0.1,
longitudeDelta: 0.1
}
}}
>
coordinate={{
latitude: 35.6812,
longitude: 139.7671
}}
title="Tokyo Tower"
subtitle="Tourist Attraction"
/>
);
};
`Event Types
`typescript
interface AnnotationEventHandlers {
onSelect?: (event: mapkit.EventBase) => void;
onDeselect?: (event: mapkit.EventBase) => void;
onDrag?: (event: mapkit.EventBase) => void;
onDragStart?: (event: mapkit.EventBase) => void;
onDragEnd?: (event: mapkit.EventBase) => void;
}
`Usage Examples
$3
`tsx
`$3
`tsx
`$3
`tsx
const MapWithAnnotations = () => {
const handleAnnotationSelect = (event: mapkit.EventBase) => {
// Common handler for all annotations
const { title, data } = event.target;
console.log('Selected location:', title);
console.log('Custom data:', data);
}; return (
);
};
`$3
`tsx
`These event handlers are available for all annotation types (
MarkerAnnotation, ImageAnnotation, CustomAnnotation).Advanced Features
$3
Create custom annotations with your own React components:
`tsx
import { CustomAnnotation } from '@1amageek/mapkit';const CustomPin = () => (
coordinate={{
latitude: 35.6812,
longitude: 139.7671
}}
>

);
`$3
Add various types of overlays to your map:
`tsx
import { CircleOverlay, PolylineOverlay, PolygonOverlay } from '@1amageek/mapkit';const MapWithOverlays = () => (
);
`$3
The library provides built-in error handling:
`tsx
const MapComponent = () => (
onMapError={(error) => {
console.error('Map error:', error);
}}
errorComponent={Failed to load map}
loadingComponent={Loading map...}
/>
);
``| Prop | Type | Required | Description |
|------|------|----------|-------------|
| fetchToken | () => Promise
| options | MapKitInitOptions | No | Initialization options |
| onError | (error: MapKitError) => void | No | Error handler |
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| id | string | No | Map container ID |
| options | mapkit.MapConstructorOptions | No | Map configuration options |
| location | Coordinate | No | Center Coordinate |
| region | Region | No | Map region with center and span |
| onMapError | (error: Error \| MapKitError) => void | No | Error handler |
| onAppear | (map: mapkit.Map) => void | No | Called when map is ready |
| onChange | (map: mapkit.Map, newAnnotations: mapkit.Annotation[]) => void | No | Called when annotations/overlays change |
| className | string | No | Additional CSS classes |
| loadingComponent | ReactNode | No | Custom loading component |
| errorComponent | ReactNode | No | Custom error component |
| onRegionChangeStart | (event: mapkit.EventBase
| onRegionChangeEnd | (event: mapkit.EventBase
| onRotationStart | (event: mapkit.EventBase
| onRotationEnd | (event: mapkit.EventBase
| onScrollStart | (event: mapkit.EventBase
| onScrollEnd | (event: mapkit.EventBase
| onZoomStart | (event: mapkit.EventBase
| onZoomEnd | (event: mapkit.EventBase
| onMapTypeChange | (event: mapkit.EventBase
| onUserLocationChange | (event: mapkit.EventBase
| onUserLocationError | (event: mapkit.EventBase
| onSingleTap | (event: mapkit.EventBase
| onDoubleTap | (event: mapkit.EventBase
| onLongPress | (event: mapkit.EventBase
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.