Sync
Synchronized multi-map component where panning, zooming, or rotating one map updates all others in real-time.
Installation
First, make sure you have the base map component installed:
npx shadcn@latest add https://www.terrae.dev/map.jsonThen install the sync component:
npx shadcn@latest add https://www.terrae.dev/sync.jsonVertical Layout
Use layout="vertical" to stack maps vertically. This works well for narrow containers or when comparing maps that benefit from a top-bottom view.
Four-Map Grid
Pass four maps with layout="grid" to create a 2x2 grid. This allows comparing multiple styles simultaneously - street, satellite, light, and dark themes all synced together.
Satellite Comparison
Compare satellite imagery with labeled satellite views to understand how street overlays enhance navigation.
Navigation Styles
Compare day and night navigation styles to see how maps adapt for different driving conditions.
Terrain Comparison
Use pitch to tilt the maps and compare how different styles render mountainous terrain. The grid layout with four maps makes it easy to compare multiple perspectives at once.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
accessToken | string | required | Mapbox access token |
maps | MapConfig[] | required | Array of 2 or 4 map configurations |
layout | "horizontal" | "vertical" | "grid" | "horizontal" | Layout arrangement for the maps |
showLabels | boolean | false | Show labels on each map panel |
center | [number, number] | [0, 0] | Initial map center as [longitude, latitude] |
zoom | number | 2 | Initial zoom level |
pitch | number | 0 | Map tilt angle (0-85 degrees) |
bearing | number | 0 | Map rotation (-360 to 360 degrees) |
projection | string | "mercator" | Map projection type |
loader | ReactNode | Globe spinner | Custom loading indicator |
Map Configuration
Each map in the maps array accepts these properties:
| Property | Type | Description |
|---|---|---|
style | string | Mapbox style URL (overrides theme) |
styles | { light?: string, dark?: string } | Theme-aware style URLs |
label | string | Custom label for the map panel |
Notes
- Each map is a separate Mapbox instance, which means billing applies per map
- Synchronization is bidirectional - interact with any map to update all others
- The grid layout requires exactly 4 maps; 2 maps work with horizontal or vertical layouts
- Movement sync uses Mapbox's move event for smooth, real-time updates
- Custom labels can be set per map, or use the default position-based labels
Comparison vs Sync
MapCompare shows two maps side-by-side without synchronization - each map can be panned independently. MapSync keeps all maps synchronized - moving one moves all. Use MapCompare when you want independent exploration, use MapSync when you want to compare the same location across different styles.