#What is Terrae?

Terrae is a modern, open-source React library that brings beautiful, interactive maps to your applications using simple, declarative components rather than imperative Mapbox GL JS code. It's tailored for React developers (especially those using shadcn/ui) who want to add maps with minimal boilerplate, full customization, and a clean, component-based API. By leveraging Mapbox GL JS under the hood while exposing everything through React props and children, it makes common map patterns like markers with popups, animated paths, clusters, choropleths, and environmental overlays feel natural in React. Ideal for dashboards, location-based apps, data visualizations, real estate sites, or any project needing elegant map experiences with Tailwind styling and shadcn/ui compatibility.

#Features ⚡

• Declarative API: Replace verbose Mapbox imperative code with clean, prop-based components and children.

• Composable Components: Nest markers, popups, polygons, animated lines, videos, clusters, and more intuitively.

• shadcn/ui Companion: Matches Tailwind aesthetics and philosophy—easy to integrate into shadcn/ui projects.

• Rich Map Interactions: Built-in support for markers, popups, pulses, animated circles/lines, choropleths, minimaps, camera controls, and follow behaviors.

• Environment & Nature Focus: Includes specialized components like Blur Area and Rain Radar for atmospheric or environmental visualizations.

• Tailwind CSS Powered: Full styling control using utility classes and consistent design tokens.

• TypeScript Ready: Fully typed components for safe, maintainable development.

• Not Production-Ready Yet: Early-stage library with active development and planned updates (e.g. new environment/nature components).

#Pros ✅

• Much cleaner and more React-idiomatic than raw Mapbox GL JS code.

• Perfect visual and workflow fit for shadcn/ui users—no style mismatch.

• Highly composable—build complex maps by nesting components naturally.

• Open-source with active development and community interest.

• Strong focus on beautiful, animated, and interactive map experiences.

#Cons ⚠️

• Not production-ready—expect breaking changes and use with caution.

• Depends on Mapbox GL JS (requires Mapbox access token for production use).

• Still early stage—fewer components and less battle-tested than established map libraries.

• React-only (no Astro or other framework support mentioned).

#Included Components - Templates

• MapMarker: Core marker with custom content and popup support.

• MarkerPopup: Attachable popup content for markers.

• Polygon: Draw and style polygon shapes.

• Pulse: Animated pulsing marker effect.

• Animated Line: Smooth animated paths/routes.

• Animated Circle: Growing/shrinking animated circles.

• Cluster: Marker clustering for dense data.

• Choropleth: Data-driven color-filled regions.

• Compare: Side-by-side map comparison slider.

• MiniMap: Small overview map control.

• Camera: Control map position, zoom, and bearing.

• Follow: Auto-follow a moving marker or path.

• Blur Area: Atmospheric blur/glow effects.

• Rain Radar: Weather-style radar overlay.

• Additional: Image, Video, and environment-focused components.

#Pricing 💸

• Completely free and open-source.

• No paid tiers or restrictions—all components and documentation are fully accessible.

• MIT licensed (via GitHub repository).

#Integrations 🧰

• React: Primary framework for all components.

• Mapbox GL JS: Core mapping engine (requires access token).

• Tailwind CSS: Styling foundation with utility-first approach.

• TypeScript: Full type safety.

• shadcn/ui: Designed as a perfect stylistic and workflow companion.

• GitHub: Source available at github.com/alamenai/terrae.