1. Overview
2. Style Syntax
   1. Map Features
   2. Stylers
   3. Style Array Example
3. Changing the Default Map Style
4. Creating a StyledMapType
5. The Styled Map Wizard

Overview

Styled maps allow you to customize the presentation of the standard Google base maps, changing the visual display of such elements as roads, parks, and built-up areas.

There are two ways to apply styles to a map:

• By setting the .styles property of the map's MapOptions object. This approach changes the style of the standard map types (base imagery in terrain and satellite views is not affected, but roads, labels, etc. respect styling rules). See Changing the Default Map Style.

• By creating and defining a StyledMapType and applying it to the map. This creates a new map type, which can be selected from the map type control. See Creating a StyledMapType.

Both approaches take an array of MapTypeStyles, each of which is composed of selectors and stylers. Selectors specify what map components should be selected for styling, while stylers specify the visual modification of those elements.

Style Syntax

Styled maps use two concepts to apply colors and changes to a map:

• Map features are the geographic elements that can be targeted on the map. These include roads, parks, bodies of water, and more, as well as their labels.
• Stylers are color and visibility properties that can be applied to map features. They define the display color through a combination of hue, color, and lightness/gamma values.

Map features and stylers are combined into a style array, which is passed to the default map's MapOptions object, or to the StyledMapType constructor. The array takes the following form:

var stylesArray = [
  {
    featureType: '',
    elementType: '',
    stylers: [
      {hue: ''},
      {saturation: ''},
      {lightness: ''},
      // etc...
    ]
  },
  {
    featureType: '',
    // etc...
  }
]

Its component pieces are described below.

Map Features

A map consists of a set of features, such as a road or park, which are specified using a MapTypeStyleFeatureType. The feature types form a category tree, with all as the root. The full list of features for selection within a map is documented in the Maps Javascript API V3 Reference. Specifying the feature as all will select all map elements.

Features are specified using the syntax, featureType: 'feature'.

For example:

{
  featureType: "road"
}

Some feature type categories contain sub-categories which are specified using a dotted notation (landscape.natural or road.local, for example). If the parent feature (road, for example) is specified, then styles applied to this selection will be applied to its children, too.

Additionally, some features on a map contain different elements. A road, for example, consists of not only the graphical line (geometry) on the map, but also the text denoting its name (labels). Elements within features are selected by specifying a category of type MapTypeStyleElementType. The following element types are supported:

• all (default) selects all elements of that feature.
• geometry selects all geometric elements of that feature.
  • geometry.fill selects only the fill of the feature's geometry.
  • geometry.stroke selects only the stroke of the feature's geometry.
• labels selects only textual labels associated with that feature.
  • labels.icon selects only the icon displayed within the feature's label.
  • labels.text selects only the text of the label.
  • labels.text.fill selects only the fill of the label. The fill of a label is typically rendered as a colored outline that surrounds the label text.
  • labels.text.stroke selects only the stroke of the label's text.

The following specification selects the labels for all local roads:

{
  featureType: "road.local",
  elementType: "labels"
}

Stylers

Stylers are formatting options of type MapTypeStyler which are applied to map features. The following MapTypeStyler options are supported:

• hue (an RGB hex string) indicates the basic color.
• lightness (a floating point value between -100 and 100) indicates the percentage change in brightness of the element. Negative values increase darkness (where -100 specifies black) while positive values increase brightness (where +100 specifies white).
• saturation (a floating point value between -100 and 100) indicates the percentage change in intensity of the basic color to apply to the element.
• gamma (a floating point value between 0.01 and 10.0, where 1.0 applies no correction) indicates the amount of gamma correction to apply to the element. Gammas modify the lightness of hues in a non-linear fashion, while not impacting white or black values. Gammas are typically used to modify the contrast of multiple elements. For example, you could modify the gamma to increase or decrease the contrast between the edges and interiors of elements. Low gamma values (< 1) increase contrast, while high values (> 1) decrease contrast.
• inverse_lightness (if true) simply inverts the existing lightness. This is useful, for example, for quickly switching to a darker map with white text.
• visibility (on, off, or simplified) indicates whether and how the element appears on the map. A simplified visibility removes some style features from the affected features; roads, for example, are simplified into thinner lines without outlines, while parks lose their label text but retain the label icon.
• color (an RGB hex string) sets the color of the feature.
• weight (an integer value, greater than or equal to zero) sets the weight of the feature, in pixels. Setting the weight to a high value may result in clipping near tile borders.

The color of a feature may be set with either a single color value, or modified by combination of hue, saturation and lightness. These properties represent two different methods of representing color but it's possible to combine the two methods. For example, you might set a color and then alter the saturation and lightness to fade out the map when displaying a dialog. For more information on color models, see The Hue, Saturation, Lightness Model documentation.

Styler rules are applied in the order they appear within the MapTypeStyler array. Do not combine multiple operations into a single styler operation; instead, define each operation as a separate entry in the styler array. Order is important, as some operations are not commutative. Features and/or elements that are modified through styler operations (usually) already have existing styles; the operations act on those existing styles, if present.

The Hue, Saturation, Lightness Model

Styled maps use the Hue, Saturation, Lightness (HSL) model to denote color within the styler operations. These operations to define color are common within graphic design. Hue indicates the basic color, saturation indicates the intensity of that color, and lightness indicates the relative amount of white or black in the constituent color.

While hue takes an HTML hex color value, it only uses this value to determine the basic color, not its saturation or lightness, which are indicated separately.

RGB hue values which consist of equal parts Red, Green and Blue — such as "#000000" (black) and "#FFFFFF" (white) and all the pure shades of gray — do not indicate a hue whatsoever, as none of those values indicate an orientation in the HSL coordinate space. To indicate black, white or gray, you must remove all saturation (set the value to -100) and adjust lightness instead.

Additionally, when modifying existing features which already have a color scheme, changing a value such as hue does not change its existing saturation or lightness.

Styler Examples

To display a feature as bright blue:

stylers: [
  { hue: "#00d4ff" },
  { saturation: 60 },
  { lightness: -20 },
  { gamma: 1.51 }
]

To display a feature as bright green, using a single RGB value:

stylers: [
  { color: "#99FF33" }
]

To remove all color from a feature, regardless of its starting color:

stylers: [
  { saturation: -100 }
]

To hide a feature completely:

stylers: [
  { visibility: "off" }
]

Style Array Example

The map feature selectors and the styler rules are combined into a style array. Any number of features can be targeted in a single array.

The following example turns all map features to gray, then colors arterial road geometry in blue, and hides business labels completely:

var styleArray = [
  {
    featureType: "all",
    stylers: [
      { saturation: -80 }
    ]
  },{
    featureType: "road.arterial",
    elementType: "geometry",
    stylers: [
      { hue: "#00ffee" },
      { saturation: 50 }
    ]
  },{
    featureType: "poi.business",
    elementType: "labels",
    stylers: [
      { visibility: "off" }
    ]
  }
];

Changing the Default Map Style

To modify the styles of the default map type (changes to labels and roads will also affect terrain and satellite maps), set the style array in the map's MapOptions either at time of construction or by calling setOptions.

The following example reduces the saturation on all features and disables labels on roads.

var styles = [
  {
    stylers: [
      { hue: "#00ffe6" },
      { saturation: -20 }
    ]
  },{
    featureType: "road",
    elementType: "geometry",
    stylers: [
      { lightness: 100 },
      { visibility: "simplified" }
    ]
  },{
    featureType: "road",
    elementType: "labels",
    stylers: [
      { visibility: "off" }
    ]
  }
];

map.setOptions({styles: styles});

See Map Features for information about the elements of the map that can be styled; see Stylers for the colors and effects that can be applied.

Creating a StyledMapType

You can create a new map type to which to apply styles, by creating a StyledMapType and passing the feature and styler information to the constructor. This approach does not affect the style of the default map types.

To create a new map type:

1. Create your array of styles. See Map Features and Stylers for instructions.
2. Create a new google.maps.StyledMapType object, passing it the array of styles, as well as a name for the new map type.
3. Create your map object and, in the map options, include an identifier for the the new map type in the mapTypeIds array (which is a property of the mapTypeControlOptions object).
4. Associate the identifier in the last step with the new styled map.
5. Set the map to use the new map type.

function initialize() {

  // Create an array of styles.
  var styles = [
    {
      stylers: [
        { hue: "#00ffe6" },
        { saturation: -20 }
      ]
    },{
      featureType: "road",
      elementType: "geometry",
      stylers: [
        { lightness: 100 },
        { visibility: "simplified" }
      ]
    },{
      featureType: "road",
      elementType: "labels",
      stylers: [
        { visibility: "off" }
      ]
    }
  ];

  // Create a new StyledMapType object, passing it the array of styles,
  // as well as the name to be displayed on the map type control.
  var styledMap = new google.maps.StyledMapType(styles,
    {name: "Styled Map"});

  // Create a map object, and include the MapTypeId to add
  // to the map type control.
  var mapOptions = {
    zoom: 11,
    center: new google.maps.LatLng(55.6468, 37.581),
    mapTypeControlOptions: {
      mapTypeIds: [google.maps.MapTypeId.ROADMAP, 'map_style']
    }
  };
  var map = new google.maps.Map(document.getElementById('map_canvas'),
    mapOptions);

  //Associate the styled map with the MapTypeId and set it to display.
  map.mapTypes.set('map_style', styledMap);
  map.setMapTypeId('map_style');
}

The resulting map is shown below. Notice the new button at top-right of the map; this is the new map type created in the example code.

See Map Features for information about the elements of the map that can be styled; see Stylers for the colors and effects that can be applied.

The Styled Map Wizard

Creating styles by hand and testing your code to see how they look is potentially time-consuming. Instead, you can use the Styled Map Wizard to set up the JSON for your map's styles. The wizard allows you to select features and their elements, apply operations to those features, and save the styles to JSON, which you can copy and paste into your application.