This library is not production-ready yet. Developers should use it with caution and expect breaking changes.

Changelog

Welcome to the Terrae Changelog. Here you'll find detailed updates on new features, improvements, and fixes shipped with each release.

Coming Soon

February 13, 2026

New Properties

Radar

pitchAlignment

View docs

New pitchAlignment prop for flat (viewport) or tilted (map) radar rendering. Added test coverage for rendering and marker lifecycle.

Fixes

Compass

Rotation Sync

View issue

Fixed compass rotation not staying in sync with the map bearing. Refactored internals and added tests for rendering, rotation sync, and positioning.

February 9, 2026

New Components

Animated Footprint

View docs

New MapAnimatedFootprint component for animated footprint steps that walk along a path. Uses Lucide's Footprints icon with left/right alternation, bearing-based rotation, and staggered fade-in animation. Supports looping and customizable spacing.

New MapFire component for realistic animated fire effects using particle simulation. Features rising particles with color gradient from base to tip, flickering glow effect, and customizable intensity, size, and colors.

Explosion

View docs

New MapExplosion component for animated burst effects with radial particles and center flash. Supports two types: burst for standard explosions and nuclear for mushroom cloud effects with rising fireball and shockwave. Includes useExplosionControl hook for programmatic triggering.

Cyclone

View docs

New MapCyclone component for animated cyclone funnels with swirling particles and debris. Features characteristic funnel shape, rotating debris cloud, dust base, and smooth intensity transitions. Includes useCycloneControl hook for start/stop and dynamic intensity control.

Music Disc

View docs

New MapMusicDisc component for rotating music disc with floating notes animation. Features vinyl record appearance with groove lines, customizable album cover image, adjustable spin speed, and animated music notes. Also exports a standalone MusicDisc component for use outside of maps.

Tsunami

View docs

New MapTsunami component for animated tsunami wave effects. Features an incoming wave from the sea with realistic foam crest, crashing animation with spray particles and debris, customizable wave direction, speed, and colors. Includes useTsunamiControl hook for programmatic triggering and phase tracking (approaching, crashing, receding).

Meteor

View docs

New MapMeteor component for animated meteor strikes with fiery trail and impact explosion. Supports single strikes and meteor shower mode with multiple falling meteors. Features customizable angle, colors, tail length, and impact flash. Includes useMeteorControl hook for programmatic triggering and phase tracking (falling, impact, fading).

Lightning

View docs

New MapLightning component for animated lightning bolt strikes with branching and flash effects. Features customizable bolt and flash colors, adjustable strike interval, and branch probability. Includes useLightningControl hook for programmatic strike triggering.

Sandstorm

View docs

New MapSandstorm component for atmospheric sandstorm effects with horizontal particle movement and reduced visibility. Features customizable wind direction, speed, turbulence, and haze intensity. Includes useSandstormControl hook for programmatic start/stop and dynamic intensity control.

New MapSnow component for falling snowflakes with gentle drift and wind effects. Features customizable intensity, fall speed, wind direction, and flake color. Includes useSnowControl hook for programmatic start/stop and dynamic intensity control.

New MapSteam component for rising steam effects with wispy particle animation for map locations. Features customizable intensity, drift, rise speed, and color. Includes useSteamControl hook for programmatic start/stop and dynamic intensity control.

New MapGrid component for coordinate grid overlay with latitude/longitude lines and labels. Features configurable intervals, line styling, and optional coordinate labels with customizable appearance. Perfect for navigation, scientific mapping, and military applications.

February 1, 2026

New Features

MapLibre GL Support

View docs

Terrae now works with both Mapbox GL JS and MapLibre GL JS. Swap the adapter file to use open-source map tiles without a Mapbox token.

New Components

Compass

View docs

New MapCompass component with interactive drag-to-rotate functionality. Supports t-shirt sizes (sm, md, lg, xl), optional cardinal labels, outer ring, bearing display, and auto-rotation mode.

Avatar Pin Marker

View docs

New MarkerAvatarPin component for displaying user photos in a classic teardrop-shaped map pin. Perfect for showing user locations with profile pictures.

Targeting Reticle

View docs

New MapTargetingReticle component for military-style targeting brackets with tracking and lock-on capabilities. Supports smooth tracking animation, customizable colors for locked/unlocked states, optional crosshair, and GPS coordinates display.

Circle

View docs

New MapCircle component for geographic circles with center point and radius in meters. Supports draggable repositioning, customizable fill and stroke, and dashed outlines.

Animated Circle

View docs

New MapAnimatedCircle component for animated circles with drawing outline and fill effects. Supports draw and fill animation modes, looping, and dashed strokes.

Camera Follow

View docs

New MapCameraFollow component for immersive fly-through experiences. Animates the camera along a path with automatic bearing adjustment. Supports pause/resume, looping, navigation marker, and custom duration.

Choropleth

View docs

New MapChoropleth component for data-driven region coloring. Supports linear and step color interpolation, hover highlighting, click events, and works with any GeoJSON polygon data.

New MapSync component for synchronized multi-map displays. Supports 2 or 4 maps with horizontal, vertical, or grid layouts. Panning, zooming, or rotating one map updates all others in real-time.

New MapRadar component for animated radar sweep signal overlays. Features a rotating sweep beam with gradient trail, concentric range rings, crosshair lines, and fully customizable colors and rotation speed.

Watermark

View docs

New MapWatermark component for text overlays on maps. Supports 9 position presets (center, corners, edges) and fully customizable styling via className.

New Properties

Animated Arc

Head Types

View docs

New headType prop with arrow, circle, square, and none options. Control the size with headSize.

Animated Arc

Origin & Destination Markers

View docs

New showOriginMarker and showDestinationMarker props to display dots at start and end points with custom colors.

Fixes

Animated Lines

Loop Behavior

Fixed animation restarting automatically even when loop was set to false. Animation now correctly runs once and stops unless loop is explicitly enabled.

January 25, 2026

New Components

Blur Area

View docs

New MapBlurArea component to blur specific areas on the map. Supports multiple areas, custom blur intensity, rounded corners, and interaction blocking for premium content or unexplored areas.

Polygon

View docs

New MapPolygon component for drawing static filled polygons on the map. Supports customizable fill color, stroke color, opacity, and dashed strokes.

Animated Polygon

View docs

New MapAnimatedPolygon component for drawing animated polygons with outline and fill effects. Supports three animation modes: draw, fill, and draw-then-fill.

Animated Radial Lines

View docs

New MapLineRadial component for animated curved lines spreading from a central origin to multiple destinations. Supports custom markers, traveling markers, staggered animations, and auto-curvature based on distance.

Animated Arc

View docs

New MapArcAnimated component for animated curved arc lines between two points. Supports customizable arc height, traveling markers, origin/destination markers, dash patterns, and loop animations.

New Properties

Map

autoRotate

View docs

New autoRotate and rotateSpeed props for automatic globe rotation. Only works with projection="globe".

Map

showLoader

View docs

New showLoader prop for external loader control. Also includes a new animated globe as the default loader.

Map

projection

View docs

The projection prop is now reactive. Switch between all 8 Mapbox projections dynamically at runtime.

Map

Style Presets

View docs

Built-in style presets that automatically adapt to your theme. Includes standardMapStyles, streetsMapStyles, outdoorsMapStyles, satelliteMapStyles, and navigationMapStyles.

Mini Map

draggable

View docs

New draggable prop lets users reposition the minimap anywhere within the map container.

Mini Map

rounded

View docs

New rounded prop for custom border radius. Set to a number or "full" for a circular minimap.

Mini Map

styles

View docs

New styles prop for theme-aware map styles. Minimap now automatically switches between light and dark styles based on your theme.

Map Compare

orientation

View docs

New orientation prop for horizontal or vertical layouts, and showLabels to display Before/After labels.

Fixes

Animated Lines

Theme Switching

Fixed animation breaking when switching themes. The component now properly re-adds sources and restarts animation after theme changes.

Hello, Terrae!

January 18, 2026

I'm excited to introduce Terrae—a modern, declarative map library built for design engineers who want beautiful, interactive maps without the complexity. Built with React, TypeScript, shadcn/ui, and Mapbox GL JS.

What's included in the initial release:

  • Core map component with theme support
  • Markers with customizable content and avatars
  • Popups and tooltips
  • Navigation controls (zoom, rotation, fullscreen)
  • MiniMap for context overview
  • Lines and animated route paths with dashed line support
  • Animated markers with path following
  • Animated pulse effects
  • Circle clusters for data visualization
  • Side-by-side map comparison
  • Image and video overlays
  • Rain weather effects

This is just the beginning. More components, features, and improvements are coming in future releases. Thank you for being part of this journey!

Want to shape the future of Terrae?

Your feedback and ideas help guide development priorities. Share your suggestions, feature requests, or use cases on GitHub.