OpenLayers 2allows you to lay many different types of data on top of its various data sources. Currently, there are two main ways of displaying vector feature overlays in OpenLayers 2, each with benefits and drawbacks. This document seeks to describe the differences, and ways in which each can be used.

Overlay Basics

There are two different types of feature rendering in OpenLayers 2. One type is the OpenLayers 2 Vector Overlays support, which uses vector drawing capabilities in the browser (SVG, VML, or Canvas) to display data. The other type is the OpenLayers 2 Marker Overlays support. This type of layer displays HTML image objects inside the DOM.

In general, the Vector layer provides more capabilities, with the ability to draw lines, polygons, and more. The Vector-based Layers are better maintained, and are the place where most new OpenLayers 2 development is taking place. There is more support for various styling options, and more configurability over layer behavior and interactions with remote servers.

However, the Markers layer is maintained for backwards compatibility, because there are some things you can not do with vectors as they are currently implemented, and they provide a different type of interface for event registration.

Vector Overlays

Vector Layers form the core of Vector overlays. Vector overlays are powered by adding sets of OpenLayers.Feature.Vectors to the map. These can be a number of types of geometry:

  • Point / MultiPoint
  • Line / MultiLine
  • Polygon / MultiPolygon

They are styled using the OpenLayers.Style / OpenLayers.StyleMap properties.


  • StyleMap Example:

    Use “Rules” to determine style attributes based on feature properties. This is useful for rendering based on data attributes like population.

  • Context Example:

    Use a custom Javascript function to determine feature style properties. This example shows how to use which quadrant of the world a feature is in to determine its color. Similar rules can be used to do computations on a feature property to generate a style value (like size).

  • Rotation Example:

    Vector features support advanced styling, like feature rotation. This can be used, for example, to display vehicle direction, wind direction, or other direction-based attributes.

  • Unique Value Style Example:

    A common use case is to pick a specific style value based on a key/value mapping of a feature. This example demonstrates how to do that.


Vector layer interaction is achieved through the SelectFeatureControl. This control allows selection of features, using DOM events to capture which feature is clicked on.

To handle feature events on a Vector Layer, you use the SelectFeature control, in combination with an event listener registered on the layer, on the ‘featureselected’ event.

function selected (evt) {
    alert(evt.feature.id + " selected on " + this.name);
var layer = new OpenLayes.Layer.Vector("VLayer");
layer.events.register("featureselected", layer, selected);

Once you have done this, you can add a select feature control to your map:

var control = new OpenLayers.Control.SelectFeature(layer);

The activate call will move the vector layer to the forefront of the map, so that all events will occur on this layer.

As of OpenLayers 2.7, there is no support for selecting features from more than a single vector layer at a time. The layer which is currently being used for selection is the last one on which the .activate() method of the attached select feature control was called.

Layer Types

Marker Overlays

Markers support only point geometries. They are styled only using the OpenLayers.Icon class. They do not support lines, polygons, or other complex features. Their interaction method differs significantly from vector layers.

In general, Markers are the ‘older’ way to interact with geographic data in the browser. Most new code should, where possible, use vector layers in place of marker layers.


Interaction on marker layers is achieved by registering events on the individual marker event property:

var marker = new OpenLayers.Marker(lonlat);
marker.id = "1";
marker.events.register("mousedown", marker, function() {

Any number of events can be registered, and different events can be registered for each feature.

Layer Types

Transitioning from Text Layer or GeoRSS Layer to Vectors

Many OpenLayers-applications make use of the Text Layer or GeoRSS Layer, which each parse a file (tab separated values) and displays markers an the provided coordinates. When clicking on one of the markers a popup opens and displays the content of the name and description from that location.

This behavior is relatively easy to achieve using vector layers, and doing so allows for more configurability of the behavior when clicking on a feature. Instead of being forced to use popups, you can instead cause the browser to go to a new URL, or change the behavior in other ways.

Loading Data

To mimic the loading behavior of a Text Layer or a GeoRSS Layer, there are two options:

  • Use a GML Layer – covered in this document.
  • Use a Vector Layer, with a strategy and protocol.

In either case, the way for controlling the behavior of the feature selection is the same.

Loading data with a GML Layer

The GML Layer is a simple “Load data from a URL once” data layer. You provide it a URL, and a format to use, and it will load the data from the URL, and parse it according to the format.

var layer = new OpenLayers.Layer.GML("Layer Name",
   { format: OpenLayers.Format.Text });

This will cause your data to load, displaying your data as points on the map.

Styling Data

Some data formats do not include styling information, like GeoRSS. In order to match the default OpenLayers 2 style to the default marker in OpenLayers 2, you should create a StyleMap that matches the default OpenLayers 2 style:

var style = new OpenLayers.Style({
    'externalGraphic': OpenLayers.Util.getImagesLocation() + "marker.png",
    'graphicHeight': 25,
    'graphicWidth': 21,
    'graphicXOffset': -10.5,
    'graphicYOffset': -12.5

var styleMap = new OpenLayers.StyleMap({'default':style});

var layer = new OpenLayers.Layer.GML("Layer Name",
     format: OpenLayers.Format.GeoRSS,
     styleMap: styleMap

Using a style map like this will result in no visible difference when your feature is selected. To create a different style for selection – for example, with a different marker color – you could craft a second style object, and instead create your styleMap like:

var styleMap = new OpenLayers.StyleMap({
    'default': style,
    'select': selectStyle

For more information on styling your features, see the Styling or StyleMap documentation.

Displaying Popups

The Text Layer and the GeoRSS Layer open popups containing title and description text for the feature when clicked. Replicating this behavior in your application is easy.

First, define a set of functions for managing your popup.

function onPopupClose(evt) {
    // 'this' is the popup.
function onFeatureSelect(evt) {
    feature = evt.feature;
    popup = new OpenLayers.Popup.FramedCloud("featurePopup",
                             new OpenLayers.Size(100,100),
                             "<h2>"+feature.attributes.title + "</h2>" +
                             null, true, onPopupClose);
    feature.popup = popup;
    popup.feature = feature;
function onFeatureUnselect(evt) {
    feature = evt.feature;
    if (feature.popup) {
        popup.feature = null;
        feature.popup = null;

Next, we define two event handlers on the layer to call these functions appropriately. We use the layer definition from above, and assume that the layer has been added to the map. We also add a select feature control, to actually trigger the events:

    'featureselected': onFeatureSelect,
    'featureunselected': onFeatureUnselect
selectControl = new OpenLayers.Control.SelectFeature(layer);

Combining these two sections of code will cause the map to open a popup any time the feature is selected, and close the popup when the feature is unselected or the close button is pressed.

The HTML in the fourth argument to the FramedCloud constructor is based on the type of data you are parsing. This example is based around the Text Layer, but you can do the same with a KML layer by changing the ‘title’ to ‘name’. The GeoRSS Layer could use the feature.attributes.link property in addition, to create a link to the feature.

It is worth noting that this content – passed to the FramedPopup constructor – is set using innerHTML, and as such, is subject to XSS attacks if the content in question is untrusted. If you can not trust the content in your source files, you should employ some type of stripping to remove possibly malicious content before setting the popup content to protect your site from XSS attacks.

Once you’ve done this, you can customize the behavior of your layer to your heart’s content. Change the layout of your popup HTML, change the type of popup, or change the click behavior to instead open a new window – it’s all possible, and simple, with the functionality provided by the vector layers and SelectFeatureControl.