README

Codious.Ngx-Google-Maps

A Google Maps component for Angular.

Installation

npm install @codious/ngx-google-maps
npm install @types/google.maps --save-dev

Configuration

Inside your app.module.ts file import the plugin in your NgModule.

@NgModule({
  bootstrap: [AppComponent],
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxGoogleMapsModule.forRoot({
      key: '', // your Google API key retrieved from the Google Developer Console
      language: 'en', // see https://developers.google.com/maps/documentation/javascript/localization
      libraries: 'geometry', // see https://developers.google.com/maps/documentation/javascript/libraries
      loadScript: true | false, // whether or not the <script> tag of the Google Maps API should be loaded
      options: { panControl: true, panControlOptions: { position: 9 } }, // see https://developers.google.com/maps/documentation/javascript/3.exp/reference#MapOptions
      region: 'US', // see https://developers.google.com/maps/documentation/javascript/localization#Region
    }),
  ],
})
export class AppModule {}

Usage

Once Google Maps is configured, add the custom element <ngx-google-maps></ngx-google-maps> in your view to use it. Do not forget to have some minimal css for the <ngx-google-maps>.

ngx-google-maps {
  display: block;
  height: 100vh;
  width: 100%;
}

Google Maps API loaded

The scriptLoaded event is emitted when the Google Maps API Script is completely loaded. This event is used together with other Angular components in combination with the option loadScript=false to make sure the Google Maps API Script is loaded only once.

Google Maps needs at least the library geometry. Perhaps the other Angular components that loads the Google Maps API Script doesn't include the library geometry by default. If so, add it to the libraries option of the other Angular components.

Latitude/Longitude

Provide standard latitude and longitude coordinates to center the map.

<ngx-google-maps latitude="51.037861" longitude="4.240528"></ngx-google-maps>

Address

Provide a string as an address which gets geocoded to center the map on this particular address.

<ngx-google-maps address="1600 Amphitheatre Parkway. Mountain View, CA 94043"></ngx-google-maps>

Zoom

Add a zoom attribute and supply a value to choose an appropriate zoom level. By default the zoom level is 8.

<ngx-google-maps latitude="51.037861" longitude="4.240528" zoom="15"></ngx-google-maps>

Map Type ID

Set to one of the following Google Basic Map Type. See the Google Maps documentation.

HYBRID - This map type displays a transparent layer of major streets on satellite images.
ROADMAP - This map type displays a normal street map. (This is the default map type.)
SATELLITE - This map type displays satellite images.
TERRAIN - This map type displays maps with physical features such as terrain and vegetation.

<ngx-google-maps latitude="51.037861" longitude="4.240528" mapTypeId="HYBRID"></ngx-google-maps>

Options

When you add options to the config, these options are used on all instances of <ngx-google-maps>. You can set specific options on each <ngx-google-maps> instance via the optional bindable attribute options.

<ngx-google-maps latitude="51.037861" longitude="4.240528" [options]="options1"></ngx-google-maps>
<ngx-google-maps latitude="51.037861" longitude="4.240528" [options]="options2"></ngx-google-maps>

export class AppComponent {
  public options1 = { panControl: true, panControlOptions: { position: 9 } };
  public options2 = {
    styles: [
      /* add your styles here */
    ],
  };
}

Markers

Markers can be bound to <ngx-google-maps> with the markers attribute. The markers attribute should be an array of objects with at minimum the latitude and longitude key/value pairs.

<ngx-google-maps latitude="51.037861" longitude="4.240528" [markers]="myMarkers"></ngx-google-maps>

export class AppComponent {
  myMarkers = [
    {
      animation: google.maps.Animation.BOUNCE,
      defaultIcon: '/img/myMarkerIcon.png',
      highlightIcon: '/img/myMarkerHighlightIcon.png',
      icon: '/img/myMarkerIcon.png',
      infoWindowOptions: {
        content: '<strong>insert some HTML content here</strong>',
        pixelOffset: new google.maps.Size(-13, 0),
        position: new google.maps.LatLng(51.037861, 4.240528),
        maxWidth: 300
      },
      label: 'My Marker Label',
      latitude: 51.037861,
      longitude: 4.240528,
      open: true,
      title: 'My Marker Title',
      zIndex: 1000,
      zoom: 15
    },
    { ... }
  ];
}

Supported properties

animation (optional) - google.maps.Animation constant - see Google Maps documentation
defaultIcon - string | Icon | Symbol - default icon for highlighting of the marker.
highlightIcon - string | Icon | Symbol - highlighted icon for highlighting of the marker.
icon (optional) - string | Icon | Symbol - see Google Maps documentation
infoWindowOptions (optional) - object - if set, the mapClick event will not be called, instead an infoWindow containing the given content will be shown - see Google Maps documentation
- content (required) - string | Node - content to display in the InfoWindow. This can be an HTML element, a plain-text string, or a string containing HTML.
- pixelOffset (optional) - google.maps.Size - the offset, in pixels, of the tip of the info window from the point on the map at whose geographical coordinates the info window is anchored.
- position (optional) - google.maps.LatLng - the LatLng at which to display this InfoWindow.
- maxWidth (optional) - number - maximum width of the infowindow, regardless of content's width.
label (optional) - string | MarkerLabel - see Google Maps documentation
latitude (required) - number
longitude (required) - number
open (optional) - boolean - open the InfoWindow automatically when panning to the marker.
title (optional) - string - see Google Maps documentation
zIndex (optional) - number
zoom (optional) - number - set the zoom level when panning to the marker.

Available methods

highlight - change the icon in the highlightIcon
panTo - jump to the marker, uses the open and zoom properties of the marker to automatically open the InfoWindow and set the zoom level of the map
unHightlight - change the icon back to the defaultIcon

Map Click Event

It is possible to catch the map click event as specified by the Google Maps documentation. The mapClick event is added as a CustomEvent to the <ngx-google-maps> DOM element with the event data added to the detail key.

<ngx-google-maps latitude="51.037861" longitude="4.240528" (mapClick)="myEventHandler($event)"></ngx-google-maps>

export class AppComponent {
  public myEventHandler(event): void {
    const latLng = event.detail.latLng;
    const lat = latLng.lat();
    const lng = latLng.lng();
  }
}

Automatically Close infoWindows

Automatically close the previous opened infoWindow when opening a new one, or when clicking somewhere on the map (assuming the mapClick event is not set up).

<ngx-google-maps autoCloseInfoWindows="true" latitude="51.037861" longitude="4.240528" [markers]="myMarkers"></ngx-google-maps>

Output Events

In addition to the mapClick event mentioned above, there are several output events available:

addressGeocoded - published when an address was geocoded, payload is the result from the Google Maps Geocoder.
infoWindowCloseClick - published when the infoWindow is closed by clicking the close button, payload is the InfoWindow object for the related marker.
infoWindowContentChanged - published when the content of the infoWindow has changed, payload is the InfoWindow object for the related marker.
infoWindowDomReady - published when the infoWindow is fully loaded, payload is the InfoWindow object for the related marker.
mapBoundsChanged - published when the map is dragged or zoomed, payload is the new map bounds as a LatLngBounds object.
mapClick - published when the map is clicked, payload is the event object.
mapLoaded - published when the map is created, payload is the Map object.
markerClick - published when a map marker is clicked (and no InfoWindow is defined for it), payload is the Marker object for the clicked marker.
markerMouseOut - published when the mouse exits the marker, payload is the Marker object for the exited marker.
markerMouseOver - published when the mouse enters the marker, payload is the Marker object for the entered marker.
markersChanged - published when the array of markers is added of changed, the payload are the array of markers.
scriptLoaded - published when the Google Maps API is completely loaded, without a payload.

Usage no npm install needed!