JavaScript API

Map customization

When using the preconfigured MMapDefaultSchemeLayer, you can change the appearance of most geo objects in addition to the basic map settings. For example, you can change the color of roads or buildings. To do this, pass the customization settings to the customization field.

Usage example:

const map = new MMap(element, {
  location: {center: [25.229762, 55.289311], zoom: 5},
  mode: 'vector'
});

const layer = new MMapDefaultSchemeLayer({
  customization: [
    // Change the geometry of all bodies of water to transparent.
    {
      tags: {
        all: ['water']
      },
      elements: 'geometry',
      stylers: [
        {
          opacity: 0
        }
      ]
    },
    // Change the label color of all POI and public transport network nodes.
    {
      tags: {
        any: ['poi', 'transit_location']
      },
      elements: 'label.text.fill',
      stylers: [
        {
          color: '#0000DD'
        }
      ]
    }
  ]
});
map.addChild(layer);

You can edit customization styles in the convenient online-editor.

Format

Customization is set as an array of objects. Each object describes a customization block (styler). Each block contains:

  • tags — Tags that define a subset of styled objects. For more information, see Tags. If the field is missing, styles are applied to all objects. If an unknown tag is specified, styles are not applied.
  • types — Types of styled objects. If the field is missing, styles are applied to all types of objects. Possible values:
    • point — Points. For example, bus stops, POI.
    • polyline — Polylines. For example, roads, borders, riverbeds.
    • polygon — Polygons. For example, parks, lakes.
  • elements — Elements of the object whose display properties will change. If the field is missing, styles are applied to all elements. Possible values:
    • geometry — Geometric elements of the object (a combination of geometry.fill and geometry.outline).
    • geometry.fill — Inner area (fill) of the object's geometric elements.
    • geometry.fill.pattern — Image that fills the inner area of the polygon or polyline.
    • geometry.outline — Outline of the object's geometric elements.
    • label — All elements of the object label.
    • label.icon — Object icon.
    • label.text — Text of the object label (a combination of label.text.fill and label.text.outline).
    • label.text.fill — Fill of the object label text.
    • label.text.outline — Outline of the object label text.
  • stylers — One or more stylers describing the properties to be changed. Stylers are applied in the same order they are set.

Tags

Most objects on the map have one or more classification tags. They help to identify the subset of objects that each individual customization block applies to.

"tags": {
  "all": ["tag1", "tag2", ...],
  "any": ["tag1", "tag2", ...],
  "none": ["tag1", "tag2", ...]
}

The tags fields have the following meaning:

  • all — The object must have all the specified tags.
  • any — The object must have at least one of the specified tags.
  • none — The object must not have the specified tags.

Caution.

If one of the fields contains an unknown tag, the customization block is not applied.

List of tags

  • road: Highways:
    • road_N: Highways with category of importance N ranging from 1 (most important) to 7 (least important).
    • road_limited: Roads with restricted motor traffic, pedestrian areas.
    • road_unclassified: Unclassified roads (usually in forests and fields).
    • road_minor: Intra-block passages.
    • road_construction: Roads under construction.
    • ferry: Ferry crossings.
    • path: Roads that are not suitable for motor traffic (sidewalks, park paths, and bicycle paths).
    • crosswalk: Pedestrian and bicycle crossings.
    • traffic_light: Traffic lights.
  • water: Bodies of water:
    • bathymetry: Map of the depth of reservoirs.
  • landscape: Landscape objects:
    • land: Land surface.
    • landcover: Vegetation, swamps, and glaciers:
      • vegetation: Vegetation (including lawns, urban vegetation and point plants).
    • urban_area: Urban blocks:
      • residential: Residential blocks.
      • industrial: Industrial blocks.
      • cemetery: Cemeteries.
      • park: Gardens and parks.
      • medical: Healthcare facilities.
      • sports_ground: Sports grounds and playing fields.
      • beach: Beaches.
      • construction_site: Construction sites.
      • parking: Parkings.
    • national_park: National parks and nature preserves.
    • terrain: Terrain.
  • poi: Points of interest:
    • major_landmark: Prominent objects marked with a separate icon.
    • outdoor: Outdoor playgrounds:
      • park: Gardens and parks.
      • national_park: National parks and nature preserves.
      • beach: Beaches.
    • parking: Parkings.
    • shopping: Stores and shopping malls.
    • commercial_services: Organizations providing commercial services:
      • fuel_station: Gas stations.
      • hotel: Hotels and housing.
    • food_and_drink: Restaurants and bars.
    • cemetery: Cemeteries.
    • medical: Healthcare facilities.
  • admin: Labels and borders of districts, and public spaces in localities:
    • country: Countries.
    • region: Regions or states.
    • locality: Localities.
    • district: Urban districts.
    • address: Addresses.
  • transit: Any map objects related to public transport:
    • transit_location: Any point on the map related to public transport, such as metro stations, bus stops, or entrances.
      • transit_stop: Public transport stops with passenger drop-off and pick-up.
      • transit_entrance: Entrances or exits of a metro station.
    • transit_line: Transit lines as a physical object, such as railway and tram tracks or cable lines above ground.
    • transit_schema: Schematic representation of public transit lines.
    • is_unclassified_transit: Public transport objects of unknown importance.
  • structure: Structures:
    • building: Buildings:
      • entrance: Building entrances.
    • fence: Fences.
  • is_tunnel: A section of road or track passing through a tunnel.
  • geographic_line: Equator line and polar circles.

Properties

Properties change the visual appearance of an object and are applied as follows:

  • zoom: Limits the use of styles to a range of scales. You can specify a single integer or an array of two integers (from the lesser to the greater, closed interval [zmin, zmax]).
  • visibility: Sets the visibility of the object. Possible value: off.
  • hue: Changes the hue of the object on the map without changing its saturation and brightness. Set as a base color in #RRGGBB format (see the description of the color property). For a base color with an undefined hue (white, gray, or black), the color of the object doesn't change.
  • saturation: Changes the color saturation on the map. Set as a real number from the range [-1, 1]. At -1, all colors become shades of gray. At 1, the image colors become highly saturated. At 0, the colors don't change. Shades of gray don't change.
  • lightness: Changes the brightness of colors on the map. Set as a real number from the range [-1, 1]. At -1, all colors become black. At 1, all colors become white. At 0, the colors don't change.
  • color — Changes the object color (if applied to an icon, its primary color). The following formats are supported:
    • #RGB, #RRGGBB, 0xRGB, 0xRRGGBB, RGB, RRGGBB: A string containing a HEX color code.
    • #RGBA, #RRGGBBAA, 0xRGBA, 0xRRGGBBAA, RGBA, RRGGBBAA: A string containing a HEX color code and alpha channel.
  • secondary-color: Changes the icon's secondary color. Specified in the same format as color.
  • tertiary-color: Changes the icon's tertiary color. Specified in the same format as color.
  • opacity: Defines the relative transparency of the object. Set as a real number. Works as scale for alpha: doesn't change the value but multiplies it by the color's existing alpha value. If you need to change the alpha value, set the color using the color property.
  • scale: Changes the scale of the object. Set as a real number. The size of the object is multiplied by scale.
In this article: