Aller au contenu

Composants · Référence

Google Map

A reusable Google Maps renderer with responsive radius fitting, centered overlays, accessible touch controls, shared script loading, and localized states.

Dernière mise à jour le 15 octobre 2026

Overview

GoogleMap is a product-neutral Google Maps JavaScript renderer. The host owns its browser key, location selection and layout. The component owns shared script loading, centered overlays, camera controls, localized states and cleanup. Install with bunx shadcn@latest add @krak-stack/google-map.

Install

shell
bunx shadcn@latest add @krak-stack/google-map

Usage

tsx
import { GoogleMap } from "@/components/ui/google-map";

<GoogleMap
  apiKey={googleMapsBrowserApiKey}
  center={{ lat: 45.5019, lng: -73.5674 }}
  zoom={9}
  marker={{ icon: "/map-marker.svg" }}
  radius={{ radiusMeters: 25_000, fillColor: "#2563eb", strokeColor: "#1d4ed8" }}
  fitRadius
  fitPadding={40}
  className="h-80 min-h-0 w-full"
/>

Provide a definite height through className; the default minimum height is 16rem. Dialog width, responsive columns, keyboard-safe content scrolling and action layout remain host concerns.

Responsive radius fitting

fitRadius defaults to false, preserving controlled center/zoom behavior. When enabled with a radius, Google bounds fitting keeps the complete circle visible with fitPadding pixels (default 32). Fitting runs after initialization, location/radius changes and actual nonzero container-size changes. Hidden maps fit when revealed through ResizeObserver. Manual zoom remains until those changes or the Show selected area action; styling-only overlay changes do not reset the camera. Supplied minZoom/maxZoom still constrain the camera. Extremely large padding or restrictive zoom limits can prevent full visibility.

The 44px zoom and selected-area controls have visible keyboard focus and sit above the map, away from bottom attribution. Set zoomControls={false} to hide these custom controls. interactive={false} disables dragging, gestures, scrolling, keyboard shortcuts and clickable map icons while retaining optional custom controls.

Overlays and localization

marker accepts a boolean or custom icon URL object. Radius values are meters; fillColor, fillOpacity, strokeColor, strokeOpacity and strokeWeight customize the centered circle. Set the active locale with KrakstackProvider, or override locale. The messages map supports arbitrary locale keys, with exact locale, base language and English fallback; English and French include loading, unavailable, zoom and selected-area labels.

Ajustement adaptatif

Activez fitRadius pour cadrer le cercle entier à l’ouverture, lors d’un changement de lieu ou de rayon et après un redimensionnement réel. fitPadding définit la marge en pixels. Le zoom manuel est conservé jusqu’à ces changements ou à l’action Afficher la zone sélectionnée. Les boutons mesurent 44px et offrent un focus clavier visible. Le conteneur et la disposition de la fenêtre restent sous la responsabilité de l’application.

API key and lifecycle

Use a browser key with Google Maps JavaScript API enabled and allowed-referrer restrictions. Never pass a server secret. The component reads no environment configuration. Instances share a script and should use the same key. Loading, missing-key and initialization/script failures are localized; remount to retry a failed script. Google Maps attribution, availability, billing and terms remain applicable.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies