Full API reference. For installation and quick-start usage, see the README.
Create a Leaflet map layer for visualizing data using colored/sized hexbin-based bins.
var hexLayer = L.hexbinLayer().addTo(map);Set of options for customizing the appearance/behavior of the hexbin layer.
Example:
var options = {
radius : 12,
opacity: 0.5,
duration: 200,
colorScaleExtent: [ 1, undefined ],
radiusScaleExtent: [ 1, undefined ],
colorDomain: null,
radiusDomain: null,
colorRange: [ '#f7fbff', '#08306b' ],
radiusRange: [ 5, 12 ],
pointerEvents: 'all'
};Default: 12 - Sets the radius on the hexbin layer (see below for details).
Default: 0.6 - Sets the opacity on the hexbin layer (see below for details).
Default: 200 - Sets the transition duration for the hexbin layer (see below for details).
Default: [ 1, undefined ] - Sets the extent of the color scale for the hexbin layer (see below for details).
Default: [ 1, undefined ] - This is the same exact configuration option as colorScaleExtent, only applied to the radius extent.
Default: null - This is used to override the default behavior, which is to derive the color domain from the data. Normally, you can tweak the generation of the color domain using the colorScaleExtent option. However, if you want to set a completely custom domain, you can provide it as an array of values with this option. The array of values will be passed directly into the domain of the color scale before rendering.
Default: null - This is used to override the default behavior, which is to derive the radius domain from the data. Normally, you can tweak the generation of the radius domain using the radiusScaleExtent option. However, if you want to set a completely custom domain, you can provide it as an array of values with this option. The array of values will be passed directly into the domain of the radius scale before rendering.
Default: [ '#f7fbff', '#08306b' ] - Sets the range of the color scale used to fill the hexbins on the layer.
Default: [ 4, 12 ] - Sets the range of the radius scale used to size the hexbins on the layer.
Default: 'all' - This value is passed directly to an element-level css style for pointer-events.
You should only modify this config option if you want to change the mouse event behavior on hexbins. This will modify when the events are propagated based on the visibility state and/or part of the hexbin being hovered.
Setter/getter for the data bound to the hexbin layer. The default data schema for the hexin layer is:
[ [ lng1, lat1 ], [ lng2, lat2 ], [ lng3, lat3 ]... [ lngN, latN ] ]
Where the hexbin size is fixed at the radius and the color is linearly scaled and based on the bin count (the number of points contained in the bin).
Triggers a redraw of the hexbin layer.
You should only need to use this function if you are modifying several aspects of the layer.
The only function in the API that automatically redraws is .data()
Setter/getter for the radius configuration option. Radius of the hexagon grid cells in pixels.
This value should be a positive number. This radius controls the radius of the hexagons used to bin the data but not necessarily to draw each individual hexbin.
Setter/getter for the opacity configuration option. The opacity of the visible hexagons.
This value should be a number between 0 and 1. Since we are transitioning opacity as part of d3 rendering the hexbins, this is not currently controlled by CSS. Future iterations may make this purely CSS based with the transitions applied to groups.
Setter/getter for the durations configuration option. The millisecond duration of d3 transitions between states. This value should be a non-negative number. A value of 0 means that transitions will be instantaneous.
Note: The transition duration should be set to a value lower than the minimum refresh interval of your data. What this means is that if you are going to be updating the data for the hexbin layer every 100 ms, you should keep this duration at a value of less than 100ms. The consequence of not doing this is that hexbins will not fully complete their transitions in between changes.
Setter/getter for the colorScaleExtent configuration option. This is used to override the derived extent of the color values and is specified as a tuple of the form [ min: number, max: number ]. A value of ```undefined`` for either min or max indicates that the derived value should be retained.
What this means is we derive the color value extent of the data (the min/max values in the data array) as an array of the form [ min, max ].
Once we have that tuple, we override those values with the values provided by this config option.
For example, if the derived min/max is [5, 102] and colorScaleExtent is [ 1, undefined ], the resulting extent used as the domain of the colorScale will be [ 1, 102 ].
This setting is useful when you want to be explicit about the domain of values for the hexbins.
For example, when you want consistent color scales between multiple maps or within the same map.
Setter/getter for the radiusScaleExtent configuration option.
This is the same exact configuration option as colorScaleExtent, only applied to the radius extent.
Setter/getter for the colorRange configuration option. This value is used to specify the range of the color scale used to determine the fill colors of the hexbins.
There are a lot of different ways you can specify the color range.
One option is monotone: [ '#f7fbff', '#f7fbff' ].
The most common option is a linear transition between two colors: [ '#f7fbff', '#08306b' ]
You can also create divering and discrete color scales by providing more than two values (see the examples for details).
Setter/getter for the radiusRange configuration option.
This value is used to specify the range of the radius scale used to size the drawn hexbins.
This is relevant if you are providing a custom radiusValue function and want to specify the minimum and maximum drawn hexbin size.
Note: Overriding this value will have no effect unless you provide a custom radiusValue function.
Default: d3.scaleLinear - Setter/getter for the d3 scale used to map the color of each hexbin from the color value. If you override the scale, the color range will be ignored.
Default: d3.scaleLinear - Setter/getter for the d3 scale used to map the radius of each hexbin from the radius value. If you override the scale, the radius range will be ignored.
Default: function(d) { return d[0]; } - Setter/getter for the function used to derive the value of the longitude for each object in the data array.
Default: function(d) { return d[1]; } - Setter/getter for the function used to derive the value of the latitude for each object in the data array.
Default: function(d) { return d.length; } - Setter/getter for the function used to derive the value of the color for each object in the data array.
Default: function(d) { return 1; } - Setter/getter for the function used to derive the value of the radius for each object in the data array.
Setter/getter for the function used to derive the fill for each hexbin given the object generated by the d3 hexbin layout. The default fill function will simply map to the colorScale, but use 'none' when there is an undefined or null value.
Getter for the d3 dispatch object that exposes mouse events for the hexbins.
Example:
hexLayer.dispatch()
.on('mouseover', function(d, i) {
console.log({ type: 'mouseover', event: d, index: i, context: this });
})
.on('mouseout', function(d, i) {
console.log({ type: 'mouseout', event: d, index: i, context: this });
})
.on('click', function(d, i) {
console.log({ type: 'click', event: d, index: i, context: this });
});Default: None - Setter/getter for the hover behavior.
Hover handlers help you customize hexbin hover behavior. Examples include growing the size of the hexbin in various ways or showing a tooltip. If the hover handlers don't do what you want, you can always handle events yourself or implement your own hover handler. For more details, see the section on hover handlers below.
All handlers are under the L.HexbinHoverHandler namespace.
Handlers are created as follows:
L.HexbinHoverHandler.ResizeFill(options)Here's a basic example:
// Create a hexbin layer where hexbins that are hovered will grow from their
// current radius up to the maximum radius (in this case 11)
var hexLayer = L.hexbinLayer({ duration: 400, radiusRange: [ 5, 11 ] })
.radiusValue(function(d) { return d.length; })
.hoverHandler(L.HexbinHoverHandler.resizeFill());You can combine hover handlers with CSS to achieve interesting effects. The above hover handler combined with the below CSS will grow hexbins on hover using a smooth animation and will change the stroke to orange.
.hexbin-container:hover .hexbin-hexagon {
transition: 200ms;
stroke: orange;
stroke-width: 1px;
stroke-opacity: 1;
}There are several provided hover handlers and they each may take options. They are described below.
Shows a basic tooltip centered above the hexbin.
Options:
- tooltipContent - function(d) { return 'tooltip content here'; }
Resize the hovered hexagon to fill the current hexbin.
No options required.
Resize the hovered hexagon by scaling it to be a percentage larger than the maximum drawn hexagon radius.
Options:
- radiusScale - provides the scale factor by which to increase the radius of the hexbin. Example:
radiusScale: 0.5will result in a hovered hexbin radius that is 50% larger than the maximum hexagon radius.
Combine multiple hover handlers.
Options:
- handlers - Array of hover handlers to combine.
If you want to implement (or contribute) your own hover handler, the interface is pretty simple:
L.HexbinHoverHandler.myHoverHandler = function() {
// return the handler instance
return {
mouseover: function (hexLayer, event, data) {
// hexLayer - reference to the L.HexbinLayer instance
// event - the MouseEvent that triggered the handler
// data - reference to the data bound to the hovered hexbin
// this - D3 wrapped DOM element for hovered hexbin
},
mouseout: function (hexLayer, event, data) {}
};
};Create a Leaflet map layer for visualizing transient event data using animated expanding circles.
var pingLayer = L.pingLayer().addTo(map);Set of options for customizing the appearance/behavior of the ping layer.
Example:
var options = {
duration: 800,
fps : 32,
opacityRange: [ 1, 0 ],
radiusRange: [ 5, 12 ]
};Default: 800 - Sets the transition duration for the ping layer (see below for details).
Default: 32 - Sets the target framerate for the ping animation (see below for details).
Default: [ 1, 0 ] - Sets the range of the opacity scale used to fade out the pings as they age (see below for details).
Default: [ 3, 15 ] - Sets the range of the radius scale used to size the pings as they age (see below for details).
Submit a ping to the layer. The default data schema for the ping layer is:
[ [ lng1, lat1 ], [ lng2, lat2 ], [ lng3, lat3 ]... [ lngN, latN ] ]
Where the ping radius scale factor is fixed at 1.
Setter/getter for the durations configuration option. The millisecond duration of each ping's lifecycle.
This value should be a non-negative number. The pings will grow from their initial size/opacity to their final size/opacity over this period of time. After this duration, the pings are removed from the map.
Setter/getter for the fps configuration option. The animation loop will limit DOM changes to this frequency in order to reduce the impact to the CPU.
Setter/getter for the radiusRange configuration option. The start/end radius applied during each ping's lifecycle.
This value should be a tuple of size two. The pings will start at a pixel radius equal to the first number in the tuple and animate to the second number in the tuple.
Setter/getter for the opacityRange configuration option. The start/end opacity state applied during each ping's lifecycle.
This value should be a tuple of size two. The pings will start at an opacity equal to the first number in the tuple and animate to the second number in the tuple.
Default: d3.scalePow().exponent(0.35) - Setter/getter for the scale used to determine the radius during the ping lifecycle. If you override the scale, the radius range will be ignored.
Default: d3.scaleLinear() - Setter/getter for the scale used to determine the opacity during the ping lifecycle. If you override the scale, the opacity range will be ignored.
Default: function(d) { return 1; } - Setter/getter for the scale factor applied to the radius of each ping. This can be used to differentiate different events by size.
Default: function(d) { return d[0]; } - Setter/getter for the function used to derive the value of the longitude for each object in the data array.
Default: function(d) { return d[1]; } - Setter/getter for the function used to derive the value of the latitude for each object in the data array.
Getter for the set of currently alive pings.
Getter for the actual fps (based on the actual time between the last two animation frames).