Maps API for JavaScript Developer's Guide

Default Styles

HERE provides four default embedded styles to render the basic map primitives.
  • polygons
  • lines
  • points
  • text
Depending on the geometries and attributes that the data source provides, the styles can be used interchangeably. For more information about available layers and their attributes, refer to the Vector Tile REST API documentation.

The following examples illustrate how different styles can be applied to the same data layer. The configurations, below use water layer to render the encoded data with four different styles. These universal styles are embedded and exist for all data layers and properties. A description of each style and associated style attributes is in the corresponding sections below.

The code, below uses a polygon style to render the water polygons of the blue color. The image on the right shows the map after the configuration is set as the H.map.Style of the base map.
Table 1.
Style The map after applying "polygons" style
sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      polygons:
        order: 1
        color: [0.055, 0.604, 0.914, 1.00]
Changing the polygons style to the lines styles allows you to render the outlines of the data encoded in the data layer.
Table 2.
Style The map after applying "lines" style
sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      lines:
        order: 1
        width: 2px
        color: [0.055, 0.604, 0.914, 1.00]
You can also apply the points style to the same data, which renders points in place of the geometry's vertices. The style defines the size and color of each point. Note that to see all vertices, the collide property of the style must be set to false
Table 3.
Style The map after applying the "points" style
sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      points:
        collide: false
        size: 6px
        color: [0.055, 0.604, 0.914, 1.00]
If the data layer provides properties that can have a textual representation, you can also apply text style to the layer. In the example, below the water data layer contains the name property that represents the name of the water feature. Note that for the text style, the property name is selected for rendering. You can, however, select any property - refer to the corresponding chapter of this guide for more information.
Table 4.
Style The map after applying the "text" style
sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      text:
        collide: false
        font:
          fill: rgba(0, 0, 20, 1.0)
          size: 22px
Several styles can be applied to the same data layer within the logical layer. In the example, below polygons and text styles were used to render the label information above the water polygons.
Table 5.
Style The map after applying the style that combines "text" and "polygon" style
sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      polygons:
        order: 1
        color: [0.055, 0.604, 0.914, 0.50]
      text:
        collide: false
        text_source: function() {return feature.name}
        font:
          fill: rgba(0, 0, 20, 1.0)
          size: 22px

polygons

The polygons style can be used with the data layer that contains the closed shapes. The style cannot be used with the open shapes.
  • color - string, mandatory. The property indicates the color of the feature. The string follows the CSS format of the color definitions and can take following forms:
    • CSS named colors
    • [r, g, b, a] - array that contains RGBA values in the range 0string|function1
    • '#RRGGBB' - RGB hex string
    • rgb(R, G, B) - CSS rgb color in the range 0string|function255 or 0%string|function100%
    • rgba(R, G, B, A) - CSS rgb color in the range 0string|function255 and alpha channel in the range 0string|function1
    
    draw:
      polygons:
        color: rgb(255, 0, 0)
          
  • extrude - boolean, integer, [min, max], function, optional. The property indicates if the polygon must be extruded along the Z axis (for example it might be used to extrude building outline polygon). Default value is false.
    • boolean - when set to true extrusion height is taken from the feature's height property.
    • integer - extrusion height in meters
    • [min, max] - range defines that the polygon's extrusion must start at min meters over the ground and it is extruded up to max meters over the ground.
    • function - function that returns the number, for more information see the section "Functions".
  • interactive - boolean, optional. The property indicates whether the feature can be accessed vie the API call (for example H.Map.getObjectAt call). Default value is false.
  • order - integer, function, mandatory. The property defines the rendering order of the logical layers. Layers with the higher values appear on top.
  • style - string, optional. The property references the style defined in the styles section of the configuration. For more information, see the "Custom Styles" section.
  • visible - boolean, optional. The property indicates if the feature is rendered. Default value is true.

lines

The lines style can be used with the layers that contain either open or closed shapes.
  • dash - [string|functionnumber], optional. The property contains an array of numbers and describes the dash pattern used to render the lines. It follows the general logic of the SVG dash-array. For example, the following snippet defines the dash length 2 units long with the 1 unit gaps.
    
    draw:
      lines:
        dash: [2, 1]
          
  • cap - string, optional. The property sets the shape of the line's ends and could take values butt, square and round. The default value is butt
  • color - string, mandatory. The property indicates the color of the feature. The string follows the CSS format of the color definitions and can take the following forms:
    • CSS named colors
    • [r, g, b, a] - array that contains RGBA values in the range 0...1
    • '#RRGGBB' - RGB hex string
    • rgb(R, G, B) - CSS rgb color in the range 0...255 or 0%...100%
    • rgba(R, G, B, A) - CSS rgb color in the range 0...255 and alpha channel in the range 0...1
    
    draw:
      lines:
        color: rgb(255, 0, 0)
          
  • extrude - boolean, integer, [min, max], function, optional. The property indicates if the polygon must be extruded along the Z axis (for example, it might be used to extrude building outline polygon). Default value is false.
    • boolean - when set to true extrusion height is taken from the feature's height property.
    • integer - extrusion height in meters
    • [min, max] - range defines that the polygon's extrusion must start at min meters over the ground and it is extruded up to max meters over the ground.
    • function - function that returns the number, for more information see the section "Functions".
  • interactive - boolean, optional. The property indicates whether the feature can be accessed vie the API call (for example H.Map.getObjectAt call). Default value is false.
  • join - string, optional. The property defines the shape of the line joints and can take values bevel, round and miter. The default value is miter
  • miter_limit - integer, optional. The parameter defines maximum length of the miter join. Default value is 3.
  • offset - float, [...[zl, float]], optional. The parameter sets the offset of the line segment in m or px. The offset is applied normal to the original segment orientation. The offset can be defined in meters - m or pixels - px. Possible formats are:
    • A floating point number that is used across all zoom levels.
    • An array of two-element arrays, where first element is the zoom level and the second element defines the offset. In the following example, offset is 10px at the zoom level 16 and 4px at the zoom level 19.
      
      draw:
        lines:
          offset: [[16, 10px], [19, 4px]]
                
  • order - number, function, mandatory. The property defines the rendering order of the logical layers. Layers with the higher values appear on top.
  • outline - block level element that defines the outline style of the line. It can contain any lines style parameters. The following example defines a 1 pixel black outline for the 3 pixel blue polyline.
    
    draw:
      lines:
        order: 1
        width: 3px
        color: [0.055, 0.604, 0.914, 1.00]
        outline:
          width: 1px
          color: rgb(0, 0, 0)
          
  • style - string, optional. The property references the style defined in the styles section of the configuration. For more information, see the "Custom Styles" section.
  • visible - boolean, optional. The property indicates whether feature is rendered. Default value is true.
  • width - float, [...[zl, float]], function, mandatory. The property defines width of the line. The width could be in world meters - m or pixels - px. The possible formats are:
    • A floating point or integer number, that is applied across all zoom levels.
    • An array of two-element arrays, where first element is the zoom level and the second element defines the width. In following example, the width of the line is 5 pixels at the zoom level 15 and 15 pixels at the zoom level 18:
      
      draw:
        lines:
          width: [[15, 5px], [18, 15px]]
                
    • A function that returns a floating point number.

points

The points style can be used to visualize open and closed shapes or set of points. The style draws a circle with the defined size in the location of the data point.
  • anchor - string, [...string], optional. The property defines the side of the geometry on which the feature must be rendered. Possible values are center, left, right, top, bottom, top-left, top-right, bottom-left and bottom-right. When the parameter value is defined as an array of strings, the renderer uses the first anchor where the feature does not collide with others. Default value is ['bottom', 'top', 'right', 'left']
  • collide - boolean, optional. The property changes the collision detection setting. When set to false intersecting points are discarded during the rendering. Default value is true
  • color - string, mandatory. The property indicates the color of the feature. The string follows the CSS format of the color definitions and can take following forms:
    • CSS named colors
    • [r, g, b, a] - array that contains RGBA values in the range 0...1
    • '#RRGGBB' - RGB hex string
    • rgb(R, G, B) - CSS rgb color in the range 0...255 or 0%...100%
    • rgba(R, G, B, A) - CSS rgb color in the range 0...255 and alpha channel in the range 0...1
    
    draw:
      points:
        color: rgb(255, 0, 0)
          
  • flat - boolean, optional. The property indicates if the point must be projected into the world space. When set to true the point representation will appear "flat" on the map surface and will respond to camera movements accordingly.
  • interactive - boolean, optional. The property indicates whether the feature can be accessed through the API call (for example H.Map.getObjectAt call). Default value is false.
  • offset - [integer, integer], [...[zl, [integer, integer]], optional. The parameter shifts the point from the position defined in the data layer. The offset works in the screen pixels px and can be applied to the point feature itself or to the text block element of the point feature. The offset can be also defined as an array of two element arrays, where the first element is the zoom level and the second element is [x, y] pixel coordinates. In the following example, the offset is 10 pixels on the X-axis for the zoom level 15 and -10 pixels for the zoom level 16.
    
    draw:
      points:
        offset: [[15, [10px, 0px]], [16, [-10px, 0px]]]
          
  • order - number, function, mandatory. The property defines the rendering order of the logical layers. Layers with the higher values appear on top.
  • outline - block level element that defines the outline style of the line. It can contain any lines style parameters. The following example defines a 1 pixel black outline for the 3 pixel blue polyline.
    
    draw:
      points:
        order: 1
        size: 3px
        color: [0.055, 0.604, 0.914, 1.00]
        outline:
          width: 1px
          color: rgb(0, 0, 0)
          
  • placement - string, optional. The parameter defines the placement of the point when the data layer contains polygons or lines data. Possible values are:
    • vertex - places points on the line's or polygon's vertices.
    • midpoint - places points on the geometry's segment midpoint.
    • spaced - places points along the geometry with the intervals between points provided in the placement_spacing property.
    • centroid - places the point at the geometry centroid. The data layer must provide polygons.
    Default value is vertex
  • placement_min_length_ratio - integer, [...[zl, integer]], function, optional. The parameter defines the ratio between the geometry's segment (applicable only for lines and polygons) and the point size. The parameter is used to prevent points rendering on the segments that are smaller than the point itself.
  • placement_spacing - float, [...[zl, float]], function, optional. The parameter defines the distance in screen pixels (px) between two points and is used when the placement property is set to spaced. Default value is 80px.
  • priority - integer, function, optional. The parameter defines the drawing priority of the feature. Lower number indicates higher priority, features with the higher priority are drawn first and have more chance to be rendered. Default value is Number.MAX_SAFE_INTEGER
  • size - integer, [integer, integer], [...[zl, integer]], [...[zl, [integer, integer]]], optional. The parameter defines the size of the point in px or %. When the value is set to the single integer ex. 6px the point with the 6 pixel diameter is rendered. If the parameter is set to the array of two integer values ex. [5px, 10px] - an ellipsoid is rendered with the diameter of 5 pixels on the X-axis and 10 pixels on the Y-axis.
  • style - string, optional. The property references the style defined in the styles section of the configuration. For more information see the "Custom Styles" section.
  • text - optional. The parameter represents the block level element that defines the rendering of the text label associated with the point. All parameters of the text style can be used in this block.
  • visible - boolean, optional. The property indicates if the feature is rendered. Default value is true.

text

The text style places a text label for the geometry and can be used with open or closed geometries or points. When the style is used with the open geometry (ex. line), the label is placed along the line. If the polygon is used as a source geometry, the text is placed in the centroid.
  • align - string, optional. The property sets the alignment of the text for the multiline labels. Possible values are left, center and right. Default value is center.
  • anchor - string, [...string], optional. The property defines the side of the geometry on which the feature must be rendered. Possible values are center, left, right, top, bottom, top-left, top-right, bottom-left and bottom-right. When the parameter value is defined as an array of strings, the renderer uses the first anchor where the feature does not collide with others. Default value is ['bottom', 'top', 'right', 'left']
  • collide - boolean, optional. The property changes the collision detection setting. When set to false, intersecting text labels are discarded during the rendering. Default value is true.
  • font - mandatory. Block level element that defines the appearance of the font.
    • family - string, optional. The parameter sets the typeface. Default value is Helvetica
    • fill - string, optional. The property indicates the color of the text and follows the general color definition rules. Default value is white
    • size - integer, mandatory. The parameter defines the size of the text, possible units are px, pt and em.
    • stroke - {color: string, width: integer}, optional. The parameter defines the color and width of the font outline. The following example set the stroke width to 2 pixels and the color the blue:
      
      draw:
        text:
          font:
            size: 20px
            stroke: {color: blue, width: 2px}
              
      Color and width follow general rules outlined in the size and color properties.
    • style - string, optional. The parameter defines the font style, the values could be italic and normal. Default value is normal
    • transform - string, optional. The parameter transforms the text into uppercase or lowercase register and takes accordingly lowercase and uppercase as values.
  • interactive - boolean, optional. The property indicates whether the feature can be accessed vie the API call (for example H.Map.getObjectAt call). Default value is false.
  • max_lines - integer, optional. The parameter sets the maximum number of lines that the text can occupy, and is taken into consideration only when the text wrapping is enabled (see text_wrap).
  • offset - [integer, integer], [...[zl, [integer, integer]], optional. The parameter shifts the text from the position defined in the data layer. The offset works in the screen pixels px. It can be also defined as an array of two element arrays, where the first element is the zoom level and the second element is the [x, y] pixel coordinates. In the following example, the offset is 10 pixels on the X-axis for the zoom level 15 and -10 pixels for the zoom level 16.
    
    draw:
      text:
        offset: [[15, [10px, 0px]], [16, [-10px, 0px]]]
          
  • order - number, function, mandatory. The property defines the rendering order of the logical layers. Layers with the higher values appear on top.
  • priority - integer, function, optional. The parameter defines the drawing priority of the feature. Lower number indicates higher priority, features with the higher priority are drawn first and have more chance to be rendered. Default value is Number.MAX_SAFE_INTEGER.
  • repeat_distance - integer, optional. The property defines the label frequency within the tile boundaries. The distance is measured from the center point of the label and can be treated as a bounding sphere for the current repeat_group. Default value is 256px
  • repeat_group - string, optional. The property defines the name according to how the labels are grouped. Labels from the different data layers can have the same repeat_group name. For these labels, the same repeat_distance is applied.
  • style - string, optional. The property references the style defined in the styles section of the configuration. For more information, see the "Custom Styles" section.
  • text_source - string, function, [...string|function], optional. The parameter sets the name of the property for the label text. This can be a string literal that is the name of the property, a function that returns the string literal, or an array of strings or functions. In the latter case the first non-null value is used for the label. Default value is name
  • text_wrap - integer, optional. The property sets the number of characters after the wrapped text label.
  • visible - boolean, optional. The property indicates whether the feature is rendered. Default value is true.