Map
The foundation component that handles Mapbox GL setup, theme switching, and provides context for all map features.
Installation
npx shadcn@latest add https://terrae.vercel.app/maps/map.jsonProjections
Use the projection prop to change how the map is displayed. Mapbox GL supports 8 projections including globe for 3D views, mercator (default), naturalEarth, equalEarth, and more. See the Mapbox Projections Guide for details on each projection type.
Auto-Rotating GlobeNew
Enable automatic rotation on globe projection with the autoRotate prop. Control the rotation speed with rotateSpeed (degrees per second, default: 3). This only works when projection="globe" is set.
Projection Switcher
Try different projections to see how they affect the map display. Each projection has unique characteristics suited for different use cases.
Interactive Example
Adjust map properties to see how they affect the display in real-time.
Theme Support
The Map component integrates with next-themes to automatically switch map styles when your application theme changes. By default, it uses light-v11 for light theme and dark-v11 for dark theme.
To customize, pass the styles prop with your preferred light/dark style pair. Alternatively, use the style prop to set a fixed style that remains constant regardless of theme.
Style PresetsNew
Built-in style presets are available that automatically adapt to your theme. Import and use them directly with the styles prop.
| Preset | Light Style | Dark Style | Description |
|---|---|---|---|
defaultMapStyles | light-v11 | dark-v11 | Clean, minimal styles for general use |
standardMapStyles | standard | standard | Modern 3D style with buildings and landmarks |
streetsMapStyles | streets-v12 | dark-v11 | Detailed street maps with roads, transit, and POIs |
outdoorsMapStyles | outdoors-v12 | dark-v11 | Topographic lines, trails, and natural features |
satelliteMapStyles | satellite-streets-v12 | satellite-streets-v12 | Satellite imagery with street overlays |
navigationMapStyles | navigation-day-v1 | navigation-night-v1 | Optimized for navigation with enhanced roads |
Standard Style
The standardMapStyles preset uses Mapbox Standard, a modern style featuring 3D buildings, dynamic lighting, and rich landmarks. Automatically switches to night mode in dark theme.
Style Switcher
Try different style presets to see how they affect the map display. Toggle your theme to see how each preset adapts.
styles object or a single style URL. See the Mapbox Styles API for all available styles.Custom LoaderNew
Use the loader prop to display a custom loading component while the map initializes. This is useful for branding or providing a better loading experience. The showLoader prop gives you full control over loader visibility, allowing you to keep the loader displayed until user interaction.
Properties
The Map component supports all Mapbox GL JS options. Key properties:
| Property | Type | Default | Description |
|---|---|---|---|
accessToken | string | required | Mapbox access token from your Mapbox account |
center | [number, number] | [0, 0] | Initial map center as [longitude, latitude] |
zoom | number | 2 | Initial zoom level (0-22) |
pitch | number | 0 | Tilt angle of the map (0-85 degrees) |
bearing | number | 0 | Rotation of the map (-360 to 360 degrees) |
minZoom | number | 0 | Minimum zoom level constraint |
maxZoom | number | 22 | Maximum zoom level constraint |
maxBounds | [[number, number], [number, number]] | undefined | Restrict map panning to a geographic area |
projection | string | "mercator" | Map projection type: mercator, globe, albers, equalEarth, equirectangular, lambertConformalConic, naturalEarth, winkelTripel |
style | string | undefined | Single map style URL (overrides theme-based styles) |
styles | MapThemeStyles | defaultMapStyles | Theme-aware styles object with light and dark variants. Use built-in presets like navigationMapStyles |
loader | ReactNode | default loader | Custom loading component shown while the map initializes |
showLoaderNew | boolean | undefined | Controls loader visibility. When true, forces loader to show. When false, hides loader. When undefined, uses internal loading state. |
autoRotateNew | boolean | false | Enables automatic rotation. Only works with projection="globe". |
rotateSpeedNew | number | 3 | Rotation speed in degrees per second when autoRotate is enabled. |