# @1amageek/mapkit
A React wrapper for Apple's MapKit JS, providing a seamless way to integrate Apple Maps into your React applications.
## Features
- πΊοΈ 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
## Installation
```bash
npm install @1amageek/mapkit
```
## Prerequisites
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
## Basic Usage
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 (
);
};
```
Then use the Map component:
```tsx
import { Map, MarkerAnnotation } from '@1amageek/mapkit';
```
## Event Handling
The library supports a wide range of events for the map, annotations, and user location:
### Map Events
The `Map` 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.
### Annotation Events
- `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
### User Location Events
- `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 (
);
};
```
## 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
### Basic Marker Annotation with Events
```tsx
```
### Custom Annotation with Complex Interaction
```tsx
```
### Multiple Annotations with Shared Event Handler
```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 (
);
};
```
### Image Annotation with Clustering
```tsx
```
These event handlers are available for all annotation types (`MarkerAnnotation`, `ImageAnnotation`, `CustomAnnotation`).
# Advanced Features
### Custom Annotations
Create custom annotations with your own React components:
```tsx
import { CustomAnnotation } from '@1amageek/mapkit';
const CustomPin = () => (
);
```
### Overlays
Add various types of overlays to your map:
```tsx
import { CircleOverlay, PolylineOverlay, PolygonOverlay } from '@1amageek/mapkit';
const MapWithOverlays = () => (
);
```
### Error Handling
The library provides built-in error handling:
```tsx
const MapComponent = () => (
