CARTO.js

Events

You can bind custom functions to layer events by adding listeners and callbacks to the async portions of the CARTO.js library. Active layer events are triggered by layers on your webpage that are already loaded (Tip: these are the createLayer and createVis functions that return the done event. For details, see Loading Events). Each event requires the layer to include an interactivity layer. This is useful for integrating your website with your maps, adding events for mouseovers and click events.

Note: Be mindful of using these events, as these functions can get costly if you have a lot of features on a map.

layer

layer.featureOver(event, latlng, pos, data, layerIndex)

Triggered when the user mouse hovers on any feature.

Callback arguments

Example

1
2
3
layer.on('featureOver', function(e, latlng, pos, data, subLayerIndex) {
  console.log("mouse over polygon with data: " + data);
});

layer.featureOut(layerIndex)

Triggered when the user hovers out any feature. For example, you might want to use this event if you highlight polygons on mouseover and need a way to know when to remove the highlighting after the mouse has left.

Example

1
2
3
layer.on('featureOut', function(e, latlng, pos, data, layer) {
  console.log("mouse left polygon with data: " + data);
});

layer.featureClick(event, latlng, pos, data, layerIndex)

Triggered when when the user clicks on a feature of a layer.

Example

1
2
3
layer.on('featureClick', function(e, latlng, pos, data, layer) {
  console.log("mouse clicked polygon with data: " + data);
});

Callback arguments

Same as featureOver.

layer.mouseover()

Triggered when the mouse enters in any feature. Useful to change the cursor while hovering.

layer.mouseout()

Triggered when the mouse leaves all the features. Useful to revert the cursor after hovering.

Example

1
2
3
4
5
6
7
layer.on('mouseover', function() {
  cursor.set('hand')
});

layer.on('mouseout', function() {
  cursor.set('auto')
});

layer.loading()

Triggered when the layer or any of its sublayers are about to be loaded. This is also triggered when any properties are changed but not yet visible.

Example

1
2
3
4
5
6
layer.on("loading", function() {
  console.log("layer about to load");
});
layer.getSubLayer(0).set({
  cartocss: "#export { polygon-opacity: 0; }"
});

layer.load()

Triggered when the layer or its sublayers have been loaded. This is also triggered when any properties are changed and visible.

Example

1
2
3
4
5
6
layer.on("load", function() {
  console.log("layer loaded");
});
layer.getSubLayer(0).set({
  cartocss: "#export { polygon-opacity: 0; }"
});

subLayer

sublayer.featureOver(event, latlng, pos, data, layerIndex)

Same as layer.featureOver() but sublayer specific.

Callback arguments

Same as layer.featureOver().

sublayer.featureClick(event, latlng, pos, data, layerIndex)

Same as layer.featureClick() but sublayer specific.

Callback arguments

Same as layer.featureClick().

sublayer.mouseover()

Same as layer.mouseover() but sublayer specific.

sublayer.mouseout()

Same as layer.mouseover() but sublayer specific.