Loader

The Loader object is used to load the Google Maps API. See the Load the Google Maps Javascript API page for more information.

Example usage

G.loader({ apiKey: 'MY-API-KEY', libraries: ['places']}).load().then(() => {
    G.map('map', { center: [48.864716, 2.3522] }).show();
});

Creating the Loader object

G.loader(options?: LoaderOptions): Loader

There are a few ways to setup the Loader object.

Only one Loader object is created on a page. Calling G.loader() again returns the same object. If options are passed, they are applied to the existing object with setOptions.

No parameters.

G.loader()

In this case you should either use setOptions, one of the other set... methods, or the properties to set the configuration.

const loader = G.loader();
loader.setOptions({apiKey: 'my-api-key', libraries: ['places']});
// OR
loader.setApiKey('my-api-key')
    .setLibraries(['places']);
// OR
loader.apiKey = 'my-api-key';

Pass the loader options.

G.loader(options: LoaderOptions)

Parameter	Type	Required	Description
options	LoaderOptions	Yes	The configuration options.

const loader = G.loader({apiKey: 'my-api-key', libraries: ['places']});

warning

You must at a minimum set the API key value before calling the load() function.

Loader options

Type LoaderOptions.

LoaderOptions is an object containing the configuration options for the Loader object.

Option	Type	Default	Description
apiKey	string		The Google Maps API key
libraries	Array	[]	An array of Google Maps libraries to load. A string value is ignored here. Use the libraries property or setLibraries to set a single library as a string.
version	string	weekly	The version of the Google Maps library to load.

Events

Below are the available loader events.

You can use the plain text name for the event, or you can use the event constant.

Event	Description
load	The API library is loaded.
map_load	The API library is loaded and the map is loaded and visible.
load_error	The API library could not be loaded, or a map could not be displayed. Anything waiting for the map is told through this so that it stops waiting.

Properties

Property	Type	Description
apiKey	string	Your API key for the Google Maps API
libraries	Array	An array of Google Maps libraries to load. When setting it you can also use a single string value for one library.
version	string	The version of the Google Maps library to load. Defaults to "weekly".

Methods

dispatch

dispatch(event: string): void

Dispatch an event on the loader. It's used internally to dispatch one of the loader events. You can also dispatch custom events.

loader.dispatch('myEvent');

load

load(callback?: () => void): Promise<void>

Loads the Google maps API library.

The load event is triggered after the library is loaded. If the library has already loaded then the callback is called and the promise resolves right away.

If the API key is not set then the promise is rejected with an error.

Parameter	Type	Required	Description
callback	Function		A function to call after the API library is loaded.

No parameters are passed to the callback function.

Usage

Just load the library:

loader.load();

Use the Promise:

loader.load().then(() => {
    // Do something
});

Await the promise:

async loadTheMap() {
    await loader.load();
    // Do something after loading
}

Use the callback:

loader.load(() => {
    // Do something
});

While it's an odd choice, you can do both the callback and handle the promise. They will be executed at the same time.

loader.load(() => {
    // Do something
}).then(() => {
    // Also do something
});

on

on(type: string, callback: Function): void

Add an event listener to the Loader object. This is different from the Evented on() method. The differences are:

• Event listeners are only triggered once. They are treated as a "once" event that gets removed after it's triggered. This is because the load event only happens once. Therefore, using on or once have the same effect.
• Events use EventTarget to handle setting and dispatching the event. While we don't pass any data to the callback function, you'll get the usual Event data from the EventTarget dispatchEvent function.
• You can't pass a context to the callback. If you need the this variable to reference the object this callback is called in then use an arrow function for your callback.
• If the Google Maps API has already loaded when the listener is added then the load event is dispatched again right away so that load listeners are still called.
• An error is thrown if the callback is not a function.

Parameter	Type	Required	Description
type	string	Yes	The event type.
callback	function	Yes	The callback function.

loader.on('load', () => {
    // Do something after the loader loads
});
// Use the event constant
loader.on(G.LoaderEvents.LOAD, () => {
    // Do something after the loader loads
});

once

once(type: string, callback: Function): void

Since the on listener sets events up to only be called once, this function is just syntactic sugar on top of that to make it clear in your code that the event is only called once.

Parameter	Type	Required	Description
type	string	Yes	The event type.
callback	function	Yes	The callback function.

loader.once('load', () => {
    // Same as calling loader.on()
    // Do something.
});
// Use the event constant
loader.once(G.LoaderEvents.LOAD, () => {
    // Do something after the loader loads
});

onceLoad

onceLoad(callback: Function): void

Convenience function to set up a once event callback for the load event.

Since the on listener sets events up to only be called once, this function is just syntactic sugar on top of onLoad to make it clear in your code that the event is only called once.

Parameter	Type	Required	Description
callback	function	Yes	The callback function.

loader.onceLoad(() => {
    // Same as calling loader.onLoad()
    // Do something.
});

whenLoaded

whenLoaded(): Promise<void>

Wait for the Google Maps library to load. Resolves once it's available, and rejects if it can't be loaded.

G.loader()
    .whenLoaded()
    .then(() => {
        // The Google Maps objects exist
    })
    .catch((error) => {
        // The library could not be loaded
    });

Prefer this over listening for the load event when a failure matters. That event is only dispatched on success, so waiting for it alone means waiting forever when the load fails.

Use whenMapLoaded() instead if you need a map on the page rather than just the library.

whenMapLoaded

whenMapLoaded(): Promise<void>

Wait for a map to be displayed. This is what the library's own objects wait on — markers, polylines, overlays, geocoding — when they need the Google Maps objects and the library hasn't loaded yet.

It resolves once a map has been displayed, and rejects if the library can't be loaded or a map can't be displayed.

G.loader()
    .whenMapLoaded()
    .then(() => {
        // The Google Maps objects exist and a map is on the page
    })
    .catch((error) => {
        // The library could not be loaded, or the map could not be displayed
    });

Prefer this over listening for the map_load event when you need to know either way. That event is only dispatched on success, so waiting for it alone means waiting forever when a load fails.

onceMapLoad

onceMapLoad(callback: Function): void

Convenience function to set up a once event callback for the map_load event.

Since the on listener sets events up to only be called once, this function is just syntactic sugar on top of onMapLoad to make it clear in your code that the event is only called once.

Parameter	Type	Required	Description
callback	function	Yes	The callback function.

loader.onceMapLoad(() => {
    // Same as calling loader.onMapLoad()
    // Do something.
});

onLoad

onLoad(callback: Function): void

Add an event listener to the Loader object for the load event.

This is a convenience function for setting up loader.on('load', () => {});.

See the on method for more information.

Parameter	Type	Required	Description
callback	function	Yes	The callback function.

loader.onLoad(() => {
    // Do something after the loader loads
});

onMapLoad

onMapLoad(callback: Function): void

Add an event listener to the Loader object for the map_load event.

This is a convenience function for setting up loader.on('map_load', () => {});.

See the on method for more information.

Parameter	Type	Required	Description
callback	function	Yes	The callback function.

loader.onMapLoad(() => {
    // Do something after the loader loads
});

setApiKey

setApiKey(apiKey: string): Loader

Set the Google Maps API key.

Parameter	Type	Required	Description
apiKey	string	Yes	The API key

loader.setApiKey('my-api-key');

setLibraries

setLibraries(libraries: Libraries): Loader

Set the libraries to load with Google maps.

Parameter	Type	Required	Description
libraries	Array or string	Yes	An array or libraries, or a single library as a string

Set a single library to load as an array:

loader.setLibraries(['places']);

Set a single library to load as a string:

loader.setLibraries('places');

Set multiple libraries to load:

loader.setLibraries(['geocoding', 'places']);

setOptions

setOptions(options: LoaderOptions): Loader

Set the loader object options. Only the options that are passed are changed.

Parameter	Type	Required	Description
options	LoaderOptions	Yes	The loader options.

loader.setOptions({apiKey: 'my-api-key', libraries: ['places', 'geocoding'], version: 'quarterly'});

setVersion

setVersion(version: string): Loader

Set the version of the Google Maps API to load. You only need to call this if you don't want the weekly version to be used.

Parameter	Type	Required	Description
version	string	Yes	The API version

loader.setVersion('quarterly');