When visualizing objects on a map, you might like to show some text with the visualized object. You can use Text labels can be used to further describe or classify objects on a map.

labelingsample
Figure 1. the Labeling Sample

You label your feature data by installing a FeaturePainter on a FeatureLayer, and providing it with an implementation of the paintLabel method:

paintLabel(labelCanvas, //The LabelCanvas to render the label on
           feature,     //The Feature for which a label should be rendered
           shape,       //The Shape of the Feature
           layer,       //The layer containing the feature
           map,         //The map containing the layer
           paintState   //The paint state, indicating whether the Feature is selected or not
)

In this method, you have full control over how you want to render the label, what styling you want to use, and so on. This is an example of a very straightforward implementation:

Using the name of the city as label
featurePainter.paintLabel = function(labelCanvas, feature, shape, layer, map, paintState) {
  const cityName = (feature.properties as any).CITY;
  labelCanvas.drawLabel(cityName, shape, {
    positions: PointLabelPosition.NORTH
  });
}

The LabelCanvas supports labels for points, polylines and polygons.

LuciadRIA also comes with built-in support for decluttered text labeling. Label decluttering prevents label overlap that makes the label text unreadable.

Configuring the contents and style of labels using HTML and CSS

You configure the contents and style of a label with a text string that contains a combination of HTML and CSS.

With HTML, you can define the structure and contents of your label: for example, use HTML to create labels with multiple lines, or embed image resources using an image tag.

Program: A HTML snippet representing a multi-line airspace label (from samples/common/airspaces/Airspaces.js)
var labelTemplate =
  '<div class="labelwrapper">' +
  '<div class="airspaceLabel %colorclass%">' +
  '<div class="theader">' +
  '<div class="leftTick %colortickclass%"></div>' +
  '<div class="rightTick %colortickclass%"></div>' +
  '<div class="Icao">%Icao%</div>' +
  '</div>' +
  '<div class="type">%Type%</div>' +
  '<div class="name"><div style="display: inline-block">%Name%  </div>' +
  '</div>' +
  '</div>';

Use CSS style rules to specify the styling properties of the label, like its text color, fonts, or border sizes. It is possible to apply these CSS rules to the entire label, or to small HTML fragments inside the label.

Program: A CSS stylesheet fragment that contains the styling rules of the airspace label (from samples/verticalview/vvlabels.css)
.airspaceLabel .type {
  position: relative;
  top: -0.4em;
  padding-left: 4px;
  padding-right: 4px;
  font: bold 11px arial, sans-serif;
  text-shadow: -1px 0 lightgrey, 0 1px lightgrey, 1px 0 lightgrey, 0 -1px lightgrey
}
airport labels
Figure 2. Airspace labels using HTML and CSS

The dimensions of the label must be immutable. This is important because the size of the label is taken into account during label decluttering. For more information about label decluttering, see the How to position labels article.

In practice, this means that you should not modify the contents of the label dynamically after it has been placed on the map.

For example, it is not allowed to query the DOM for the label and then insert new contents into the label. If you want the contents of the label to change over the life time of the application, you must signal such a change by calling the invalidate() method on the painter.

Another consequence of this requirement is that, if the label contains content with variable dimensions like an image tag, the width and height of the image should be absolutely defined in pixels.