<APIProvider>
Component
The APIProvider
is our component to load the Google Maps JavaScript API.
Besides that, it provides context information and functions for the other
components and hooks of this library.
It can be added at any level of the application (typically somewhere at the top of your component-tree), and it will render all child components unmodified. A re-render is only triggered once the loading status of the Maps JavaScript API changes.
Normally, there should only be a single instance of the APIProvider in a page,
but there are situations (e.g., multiple React render-roots in a page) where
this isn't possible. In those cases, make sure to create all APIProvider
components using the exact same props, since only the first one to
render will actually load the maps API.
When the Maps JavaScript API has already been loaded externally
(i.e., the google.maps.importLibrary
function exists),
the
APIProvider
will ignore all specified props and use the existing
importLibrary
function.
The Maps JavaScript API can only be loaded once, and settings like the
language and region cannot be changed after loading. Therefore, it is
important to make sure the props are specified with their final values when
the APIProvider
component is first rendered. Changing these props after the
first render will in most cases have no effect, cause an error, or both.
Usage
The APIProvider
only needs the Google Maps Platform API Key to function.
This has to be provided via the apiKey
prop:
import React from 'react';
import {APIProvider} from '@vis.gl/react-google-maps';
const App = () => (
<APIProvider apiKey={'Your API key here'}>
{/* ... any components ... */}
</APIProvider>
);
export default App;
Props
The props are based on the parameters available for the 'Dynamic Library Import' API which we are using under the hood.
Most of the props below are marked with 'first-render only', which refers to the fact that these can only be specified on first render, later changes to the values will have no effect.
Required
apiKey
: string (required, first-render only)
The API Key for the Maps JavaScript API.
Optional
version
: string (first-render only)
The version to load (defaults to weekly
).
region
: string (first-render only)
The region code to use. This alters the map's behavior based on a given country or territory. Quoting the official docs:
As the developer of a Maps JavaScript API application, you are encouraged to always set a region parameter as various services (such as Places Autocomplete) tend to provide better results when the region is set.
It is also your responsibility to ensure that your application complies with local laws by ensuring that the correct region localization is applied for the country in which the application is hosted.
language
: string (first-render only)
The language to use. This affects all text-content on the map, and the responses to service requests. The default value is determined per user based on HTTP-headers sent by the Browser.
authReferrerPolicy
: string (first-render only)
If your API key is configured for an entire subdomain,
you can set authReferrerPolicy: "origin"
to limit the amount of data sent
when authorizing requests from the Maps JavaScript API.
libraries
: string[]
A list of libraries to load immediately
(libraries can also be loaded later with the useMapsLibrary
hook).
solutionChannel
: string
To help Google to better understand types of usage of the Google Maps
JavaScript API, the query parameter solution_channel
can be set when
loading the API.
The @vis.gl/react-google-maps
library will by default set
this to a generic value unique to this library (GMP_VISGL_react
). You may
opt out at any time by setting this prop to an empty string.
Read more in the documentation.
Events
onLoad
: () => void
a callback that is called once the Maps JavaScript API finished loading.
onError
: (error: unknown) => void
a callback that is called if there is an error loading the Google Maps JavaScript API.
Context
The APIProvider creates a context value APIProviderContext
to be used by
the hooks and components in this library.
The context contains functions and data needed to register and retrieve
map-instances, libraries and the loading-status.
Client code should never need to interact with the context directly, always use the corresponding hooks instead. If you feel like you need to directly access the context, please file a bug report or feature request about this.
Hooks
The following hooks are built to work with the APIProvider
Component:
useApiIsLoaded()
anduseApiLoadingState()
to check the current loading state of the API.useMapsLibrary()
to load additional Maps Libraries.