The @vis.gl/react-google-maps library, developed by Google Maps Platform and the vis.gl team, continues to provide a powerful and streamlined way to integrate Google Maps into React. This library offers a compelling blend of React's declarative nature with the rich functionality of Google Maps.
Key Developer Benefits
-
Seamless React integration: Embed Google Maps directly as fully controlled React components, ensuring a harmonious fit within your React workflows.
-
Extensibility: Leverage custom components and utilize React hooks and context to effortlessly extend the library's capabilities.
-
vis.gl powerhouse: Integrate effortlessly with other vis.gl libraries (like deck.gl) to unlock stunning 2D and 3D data visualizations directly on top of Google Maps.
A design shift: bringing React's philosophy to the Maps JavaScript API
Two of the key points about React and other component based approaches are the Ideas of declarative / reactive programming and unidirectional data flow.
An example TypeScript that drives a simple Google Maps implementation in the declarative style of React.
In React, the user interface of an application with all its intricacies and details is fully described based on a set of variables that together form the state of the application. This state includes the data being shown, for example a list of places, but also minute details like “is this InfoWindow currently opened?” or “is the mouse currently hovering over one of those places?”. Whenever any of those state variables are changed, React will take care of updating the UI based on the new state.
State changes always propagate downwards through the component hierarchy. For example a component <PlacesList> stores a list of places, filters and sorts them, and passes them on to a number of <Place> components that describe the presentation for a single place in the list. Components lower in this hierarchy only have access to their own slice of data and need to publish events when anything about the data has to be changed (think for example clicking a “mark as favorite” button somewhere in the details for a place). This is known as the unidirectional data flow pattern: data always flows downwards, events always flow upwards.
This approach to building user interfaces scales incredibly well to even the largest applications and generally leads to reusable components and a very robust application architecture leading to greater maintainability and developer efficiency as your application grows. Deriving the entire presentation just from the state variables is also very powerful when the data from the state is stored somewhere: restoring the state guarantees that the UI and everything in it will be restored as well. This allows for easy implementation of undo/redo functions, persistence across page reloads and a lot of other use-cases.
An example TypeScript that drives a simple Google Maps implementation in an imperative style.
The Maps JavaScript API follows a different approach, often called an imperative API. With this approach, developers will more directly interact with the API by creating objects and calling methods, effectively telling the API step by step what to do instead of describing the desired outcome.
To bridge this gap between the imperative and declarative approaches, the @vis.gl/react-google-maps library provides a set of components like <Map> or <AdvancedMarker> that are used to describe in React what the map should look and behave like. This description is then translated into the corresponding instructions for the imperative Maps JavaScript API.
In some cases this is straightforward: when an <AdvancedMarker> component is added to React's component tree, the library creates a google.maps.AdvancedMarkerElement object under the hood and adds it to the map instance created for the <Map> component. When this component is later removed from the hierarchy, the marker is also removed from the map.
In other cases—for the map itself for example—it gets a bit more complicated. The map normally works as an independent component inside the page, much like a video-player for example. Within the map container, the map defines its own event-handling and user-interactions, and it maintains its own set of state-variables that are mostly hidden from users of the Maps API.
In a typical use-case, the map and its content is initialized, and once it is shown to the user, the application doesn’t need control over what happens in the map. This is perfectly fine in most situations, but there are cases where the map is more deeply integrated into the application. In those cases, we want the properties controlling the viewport of the map to come from the application-state. At the same time we’re still allowing the map to handle user-interactions like it normally would.
The @vis.gl/react-google-maps library supports both of these use-cases and more. It can be used to just display a map with some content and let the map handle everything from there, but it can also make sure that what the map shows is always perfectly synchronized with the state variables stored in the application, even to the point of taking full control over the map and disabling the maps own handling of user-interactions.
Built to stay: the philosophy behind maintaining @vis.gl/react-google-maps
First time users will notice that the @vis.gl/react-google-maps library doesn’t provide a huge amount of components to choose from. This is intentional and part of the plan to allow the library to grow and stay maintained in the open source world for a long time to come.
First off, a smaller library is obviously easier to maintain at the start, and allows maintainers to focus on getting the most important features just right before working on extended functionality. A small library is also beneficial to all users since it leads to smaller bundles. But there’s another important point about this. The goal of the library isn’t to provide a fixed collection of components for well-defined use-cases, it aims to provide a framework and the tools needed to make building any kind of use-case as easy as possible.
This also reflects in the approach chosen to implement new features: any new feature should first be implemented as an example demonstrating its use. If we notice that implementing the feature with the library is difficult, we can use that to inform improvements and low-level features to add to the library to improve on the versatility and developer experience. We also aim to write examples with reusability in mind, so developers can just copy components from the examples and use them in their applications. Features that have proven to be stable and universally useful can later be included with the library.
Developing features this way does two things: first, we ensure that there are examples as documentation available for all new features, and second, we make the code available for anyone with a similar use-case to copy and modify to their needs. Since developers will take ownership of the code by copying and adjusting it, the example code isn’t constrained by the typical problems with versioning, breaking changes and the like, so we can iterate on them more freely to find the best possible implementation.
A word on open source and the OpenJS Foundation
From its inception, @vis.gl/react-google-maps has been a champion of open-source values. Building upon the OpenJS Foundation's proven track record (which includes Node.js, jQuery, and vis.gl itself), we entrusted them with the stewardship of this library. The result: a collaborative environment where the best ideas flourish, guaranteeing the library's quality and longevity.
Google remains dedicated to ensuring that @vis.gl/react-google-maps stays up-to-date and robust. The vis.gl team, as the library's driving force, actively manages pull requests and releases.
Get started!
The promotion of @vis.gl/react-google-maps to version 1.0 is a significant milestone, but it also marks the beginning of an exciting journey. We welcome you to explore, use, and contribute to this library. Let's shape the future of mapping in React together!
Installation is as easy as npm install @vis.gl/react-google-maps or yarn add @vis.gl/react-google-maps
Find product documentation and examples on the React Google Maps website. For a structured walkthrough, with code samples, check out the codelab on the Google Maps Platform developer site. Share your experiences and creations using @vis.gl/react-google-maps. We're excited to see what you build!
