Ready 9.4.0+
GeoChartGeoChart
provides a convenient wrapper on top of D3 to display reactive
data, hiding all the complexities of D3 (opens new window). To use this
component you must install D3 (opens new window) in
your application.
To ease integration of GeoChart
there's an extensive config validator. The
JSON schema of the config is available in GeoChartConfig.js
.
Axis and data representation are completely decoupled. Each different kind of chart has a different set of requirements regarding axis and other parameters. Check out the documentation of each specific data representation for more info.
NOTE
GeoChart
API is different from D3's so you need no knowledge of
D3 (opens new window) to use it.
Optional properties
config.margin
- must be an object withtop
,right
,bottom
andleft
keys, which values are numbers. Applies this margin to the entire chart.config.animationsDurationInMilliseconds
: must be a number, allows customizing the duration of the animations.
TIP
We encourage you take a look at GeoChartConfig.js
for more info about
global settings.
Properties
Prop name | Type | Default value | Description |
---|---|---|---|
config
| object | Show description | |
debug
| boolean |
false
| Show description |
Constants
Name | Value |
---|---|
AXIS | Show definition |
BARS | Show definition |
DIMENSIONS | Show definition |
SCALES | Show definition |
NICES | Show definition |
FOCUS_ON_DOT | Show definition |
QUADRANT_LABEL | Show definition |
INTERPOLATION_TYPES | Show definition |
getTriangleShapePath | Show definition |
Examples
Playground
Chart Scales
Scales provide a way to map values from a domain (using units from a specific
context) into a range (using the units of our drawing canvas - an SVG). They
are used in several internal parts of GeoChart
but they are only defined on a
per-axis basis.
All the axis must have a type
property which must be a value of
SCALE.SCALE_TYPES
named export. Depending on the type
they have additional
requirements.
Linear scales
type
- must beSCALE.SCALE_TYPES.linear
.domain
- must be either an array of numbers (the domain will be formed by all of those numbers) or an object with anstart
and anend
property, both of them numbers. A domain may be decreasing.valueForOrigin
- value at which the axis corresponding to this scale is considered to start. This is usually0
although might be a different value. This affect each data representation in a different way, for instance, in a bar chart using this axis for its dimension, the bar's growth will be proportional to the difference between the item value and thisvalueForOrigin
. If you want to represent temperatures in Celsius degrees thisvalueForOrigin
would probably by0
but if you want to use Fahrenheit degrees it would be32
.
Example
{
"type": "linear",
"domain": {
"start": -273.15,
"end": 10000
},
"valueForOrigin": 0
}
Logarithmic scales
Almost identical to linear
scales, but:
type
- must beSCALE.SCALE_TYPES.logarithmic
.domain
- it's lowest end must be> 0
.base
- (optional) the base of the logarithm, defaults to10
.
Example
{
"type": "logarithmic",
"domain": {
"start": 1,
"end": 1024
},
"valueForOrigin": 1,
"base": 2
}
Categorical scales
Similar to linear
scales, but:
type
- must beSCALE.SCALE_TYPES.categorical
.domain
- must be an array of values which can be either strings or numbers.valueForOrigin
- must be one of the values ofdomain
array.
Optional properties
padding
- object allowing defining the separation between categories. All its properties are optional:inner
- space between two consecutive categories, in the range[0, 1]
.outer
- space before the first category and after the last one, in the range[0, 1]
.
Example
{
"type": "categorical",
"domain": ["First category", "Second category", "Third category"],
"valueForOrigin": "First category",
"padding": {
"inner": 0.1,
"outer": 0.2
}
}
Time scales
Similar to linear
scales, but:
type
- must beSCALE.SCALE_TYPES.time
.domain
- must be either an array of dates (the domain will be formed by all of those dates) or an object with anstart
and anend
property, both of them dates. A domain may be decreasing.valueForOrigin
- must be one of the values ofdomain
array.
Optional properties
nice
- function that will modify the domain to one that the ticks fit nicely in the graph. Must be one ofSCALE.NICE_TYPES
.
Example
{
"type": "time",
"domain": [new Date("2019-01-01"), new Date("2019-12-01")],
"valueForOrigin": new Date("2019-01-01"),
"nice": "timeMonth"
}
Chart axes
Axes are not only used to be rendered in the charts but also as a wrapper on top
of scales. Some charts (like bar charts)
might require references to some axes. Those references must match an axis
registered in GeoChart
.
To register axes in GeoChart
, add an array
as value of axisGroup
key in the config object. Each item of the array must be
an object with the following…
Required properties
Each axis requires these properties:
id
- a unique (GeoChart
-instance-level) identifier for this axis.keyForValues
- the key in each chart item where the value for this axis is stored.position
- the position of the axis. Should be a value ofAXIS.POSITIONS
named export or a relative position object if you want an anchored axis.scale
- the config object of the scale to be used by this axis. See scales for more info.
Anchored axis
Sometimes you might want to anchor an axis to a specific relative position
of the chart. For instance, you might want to display a vertical axis wherever
value 0
is located in the horizontal one.
NOTE
Anchoring the axis to an absolute position of the chart can be done using CSS transforms (opens new window) so it's not offered as part of the API.
Relative positions are relative to a value of a different axis so you must provide both: a value and the ID of the axis to which is relative.
So in order to use an anchored-positioned axis the position you must provide is an object with the following properties:
type
- always set toAXIS.POSITIONS.anchoredToAxis
.value
- the value to which is anchored.relativeToAxis
- the ID of the axis to which is anchored.
Customizing CSS classes
CSS classes added to the axis can be customized using cssClasses
key. Its value
should be a function which takes as parameter the classes that would be set by
default. The function should return the CSS final classes you want for that axis.
NOTE
Even though you can disable some default CSS classes, of of them are required internally and will be added regardless what you return in the function.
Customizing ticks
Ticks can be customized in several ways. To do so, add a key ticks
to the axis
config object. The value for that key must be an object with the following
properties, all of them optional:
count
- to customize the amount of ticks displayed. Must be an integer number.
NOTE
By default, d3 will only show a number of ticks which is a multiple of 2, 5 or 10. In order to force another number of ticks, use forceTickCount
associated with count
.
forceTickCount
- boolean to force the number of ticks displayed. It will create a specific number of ticks between the axis domain range.format
- function taking as first parameter the value of the axis in the domain and as second parameter its index. Should return a string with the text to be displayed as value for given tick.
Examples
Multiple axis
Anchored axis
Custom ticks
Forced tick number
Axes guidelines
Axes guidelines are lines that you might want to show in each tick of an axis to ease the viewing of a chart. Multiple guidelines can be shown associated to different axes, or even to an axis that is not being displayed in the chart.
To register axes guidelines in GeoChart
, add an array as value
of guidelinesGroups
key in the config object. Each item of the array must be
an object with the following…
Required properties
Each axis guideline requires only one of these properties:
idAxis
- the ID of the axis where we want to show guidelines.axisConfig
- axis config (see axes config) to create guidelines based on a new configuration instead of an existing axis on the chart.
Customizing CSS classes
CSS classes added to the axes guidelines can be customized using cssClasses
key.
Its value should be a function which takes as parameter the classes that would be
set by default. The function should return the CSS final classes you want for
that axis guidelines.
NOTE
Even though you can disable some default CSS classes, of of them are required internally and will be added regardless what you return in the function.
Customizing guidelines
Guidelines can be customized in several ways. To do so, add a key guidelines
to the axes guidelines config object. The value for that key must be an object
with the following properties, all of them optional:
count
- to customize the amount of guidelines displayed. Must be an integer number.outerLines
- boolean that indicates whether to show guidelines at the edges of the domain.
Examples
Axes guidelines
Customizable axes guidelines
Axes guidelines passing an axis config
Bar charts
Bar charts are collections of single items which are displayed as rectangles in a 2-dimensional grid. An arbitrary amount of different collections of items can be displayed using bar chars, each of those collections are called groups.
To add bar groups to a chart, add an array to barGroups
key of
GeoChart's config. Each item of the array
must be an object with the following...
Required properties
Each group requires these properties:
data
- collection being displayed (array).mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
). The dimension in which the rectangle will grow depending on the value.idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension. Will be used to compute proper origin and span of the bar the horizontal.idVerticalAxis
- the ID of the axis defining thevertical
dimension. Will be used to compute proper origin and span of the bar the vertical.
NOTE
idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See Axes for more info.
Optional properties
Optionally you can configure each group with an offset and a width. These are useful when you want to display multiple collections which have repeated items for the normal dimension.
TIP
Normal dimension is the dimension perpendicular to the group's mainDimension
.
For instance, if you set mainDimension
to horizontal
then the
normal dimension will be vertical
.
To allow maximum flexibility GeoChart
does not prevent overlaps. To prevent
bars from different groups from overlapping you'll have to set a width
and an offset
.
Width defines the span of the rectangle in the normal dimension. The span in the group
dimension
is computed just using the value associated to that item in the corresponding axis, however, this is not appliable in all the scenarios (a classic one is a bar chart displaying a set of categories and for each category a numeric value - like an expenses by category chart - with the width you can customize the span of the bars in the categorical axis).Offset defines the translation in the normal dimension that must be applied to the bars in order to not overlap. This is not enough to prevent overlapping since by default in some axis the width is all the available space so there doesn't exist a translation which would prevent an overlap.
Both of them can be expressed either in absolute or natural units:
- Absolute means in the same units as the underlying SVG coordinate space. You can think of this as just pixels (although they are not strictly just pixels and they might not directly translate 1:1 to screen pixels).
- Natural means in the same units as the axis used for the normal dimension.
For instance, if you have an axis of seconds, then a
naturalOffset
ofN
is an offset ofN
seconds. If the axis are categories then the absolute value for an offset ofN
is the absolute value forN
categories.
You can choose either absolute or natural values for width and offset independently, so the offset can be set to natural units while the width is set to absolute.
There are 2 exclusive properties available to customize the width:
width
- if you want to use absolute units.naturalWidth
- if you want to use natural units.
There are 2 exclusive properties available to customize the offset:
normalOffset
- if you want to use absolute units.naturalNormalOffset
- if you want to use natural units.
NOTE
You can't set both width
and naturalWidth
or normalOffset
and
naturalNormalOffset
. Doing so will throw an invalid config error.
Tooltips
Each bar can customize the tooltip displayed when it's hovered by setting the
key tooltip
. This key must store an object with the following shape:
content
- Required. Function that takes as parameters the item corresponding to the bar being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- Optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each bar can customize its CSS classes by setting a function for key cssClasses
.
This function takes as parameters the array of classes that would be set by
default, the item corresponding to the bar being customized and its position
inside the data array.
Examples
Categorical chart
Multiple series with tooltip
Interactive multi-series categorical chart
Labels
Sometimes you might want to add custom labels to the chart, anchored to the items already displayed in it, even multiple labels for each item in the chart. A collection of labels associated to a single item of the chart is what we call a label group.
You can also add labels related to values to the bar charts. To add it, you have to add the isPositioningLabelsInBars boolean to the bar chart config.
To add label groups to a chart, add an array to labelGroups
key of
GeoChart's config. Each item of the array must be an object with
the following…
Required properties
idVerticalAxis
- ID of the axis used to position the label vertically.idHorizontalAxis
- ID of the axis used to position the label horizontally.data
- an array of items to which labels will be added. Eachdata
entry must have a value for the key used by the axis referenced inidVerticalAxis
andidHorizontalAxis
(if there is idHorizontalAxis). That value will be used to compute label's vertical position. There's another key that must be present:labels
key. It must be an array whose items follows the structure describe in Labels structure section.
Optional properties
nComparisons
: The number of bar groups if there is compared bar groupsShould be bigger than or equal 2.
Labels structure
Each label has only one required property, text
, which is the string to be
displayed. However, there are several optional properties:
padding
- (optional) object withtop
,right
,bottom
andleft
keys, whose values are numbers. It is the padding to be applied to the text.margin
- (optional) object withtop
,right
,bottom
andleft
keys, whose values are numbers. It is the margin to be applied to the text container. You can combinepadding
andmargin
to render boxed text or just add some space between consecutive labels.cornerRadius
- (optional) radius of the border of the box containing the text, in units of the canvas (usually, you can think of this as just pixels).cssClasses
- function taking as first parameter an array of CSS classes that would be added by default to the group containing the text. Must return the array of final CSS classes that container must have. Required classes will be added regardless you not returning them.
Examples
Pills axis chart
Bar Chart with Vertical Labels
Bar Chart with Horizontal Labels
Color bar charts
Similarly to bar charts, Colored bar charts are collections of grouped bars which are displayed as stacked rectangles in a 2-dimensional grid. An arbitrary amount of different collections of grouped bars can be displayed using colored bar charts, each of those collections are called groups.
To add colored bar groups to a chart, add an array to colorBarGroups
key
of GeoChart's config. Each item of the array must be an object with
the following…
Required properties
data
- collection of highlighted elements being displayed (array).mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
). The dimension in which the stacked rectangles will be positioned.idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension. Will be used to compute proper origin and span of the bar if the dimension is horizontal or the width of each individual group if the dimension is vertical.idVerticalAxis
- the ID of the axis defining thevertical
dimension. Will be used to compute proper origin and span of the bar if the dimension is vertical or the width of each individual group if the dimension is horizontal.normalValue
- value to position the colorBar in the normal (numerical) axis. The value must be contained within the linear axis domain.
NOTE
idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See axes for more info.
Optional properties
Optionally you can configure each group with an offset and a width. These are useful when you want to display multiple collections which have repeated items for the normal dimension.
TIP
Normal dimension is the dimension perpendicular to the group's mainDimension
.
For instance, if you set mainDimension
to horizontal
then the
normal dimension will be vertical
.
To allow maximum flexibility GeoChart
does not prevent overlaps. To prevent
bars from different groups from overlapping you'll have to set a width
and an offset
.
Width defines the span of the rectangle in the normal dimension. The span in the group
mainDimension
is computed just using the value associated to that item in the corresponding axis, however, this is not appliable in all the scenarios (a classic one is a bar chart displaying a set of categories and for each category a numeric value - like an expenses by category chart - with the width you can customize the span of the bars in the categorical axis).HighlightedWidth is defined exactly the same as width, with the difference that this property is only applied to the items passed as data within each of the
colorBarGroups
. The highlighted items will have by default a black stroke, with the user being able to customize the extra width applied to each one of the items.Offset defines the translation in the normal dimension that must be applied to the bars in order to not overlap. This is not enough to prevent overlapping since by default in some axis the width is all the available space so there doesn't exist a translation which would prevent an overlap.
Both of them can be expressed either in absolute or natural units:
- Absolute means in the same units as the underlying SVG coordinate space. You can think of this as just pixels (although they are not strictly just pixels and they might not directly translate 1:1 to screen pixels).
- Natural means in the same units as the axis used for the normal dimension.
For instance, if you have an axis of seconds, then a
naturalOffset
ofN
is an offset ofN
seconds. If the axis are categories then the absolute value for an offset ofN
is the absolute value forN
categories.
You can choose either absolute or natural values for width and offset independently, so the offset can be set to natural units while the width is set to absolute.
There are 2 exclusive properties available to customize the width:
width
- if you want to use absolute units.naturalWidth
- if you want to use natural units.
There are 2 exclusive properties available to customize the highlightedWidth:
highlightedWidth
- if you want to use absolute units.naturalHighlightedWidth
- if you want to use absolute units.
There are 2 exclusive properties available to customize the offset:
normalOffset
- if you want to use absolute units.naturalNormalOffset
- if you want to use natural units.
NOTE
You can't set both width
and naturalWidth
, highlightedWidth
and naturalHighlightedWidth
, or normalOffset
and naturalNormalOffset
.
Doing so will throw an invalid config error.
Examples
width
and highlightedWidth
values
Horizontal color bar with naturalWidth
and naturalHighlightedWidth
values
Horizontal color bar with width
and highlightedWidth
values
Vertical color bar with naturalWidth
and naturalHighlightedWidth
values
Vertical color bar with Line charts
Use this chart to display information as a series of data points connected by straight line segments. This chart can be used in combination with GeoChartBars.
To add line groups to a chart, add an array to lineGroups
key of
GeoChart's config. Each item of the array must be an object with
the following:
Required properties
data
- array of objects, each one representing an item with two values that will be converted intox, y
point coordinates across the axes.mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
).idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension.idVerticalAxis
- the ID of the axis defining thevertical
dimension.
NOTE
Note: idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See axes for more info.
Optional properties
lineWidth
- width in pixels of each one of the lines. If no width is provided, a default width of2px
will be applied.hoverCircleRadius
- radius in pixels of the circles that will be displayed when hovering on the graph. If no width is provided, a default width of2px
will be applied.interpolationFn
- choose one of the functions provided by D3 to handle the interpolation of the segments connecting each one of your data points. Defaults tod3.curveLinear
.trackByKey
- define this function to let D3 know which property of your data will be used to track changes in it.
Tooltips
Each line can customize the tooltip displayed when it's hovered by setting the
key tooltip
. This key must store an object with the following shape:
content
- required. Function that takes as parameters the item corresponding to the line being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each line can customize its CSS classes by setting a function for key cssClasses
.
This function takes as parameters the array of classes that would be set by
default, the item corresponding to the line being customized and its position
inside the data array.
Examples
Horizontal line chart without data
Categorical line chart
Horizontal line chart
Horizontal line chart with some data missing
Horizontal line chart with top axis
Horizontal line chart with anchored axis
Hozirontal multiline chart
Horizontal multiline chart with negative values
Horizontal line chart with bars
Horizontal time line chart
Vertical line chart
Vertical line chart with left axis
Vertical line chart with anchored axis
Line segments charts
Line segments charts are collections of grouped segments intersected by circles across an axis. This chart can be used in combination with GeoChartAnchoredShapes to compare several values across an axis, each stop being the relative position of each value with the rest.
To add line segments groups to a chart, add an array to lineSegmentsGroups
key of GeoChart's config. Each item of the array must be an object
with the following…
Required properties
data
- collection of dots (stops) that will be distributed across the axis, filling the rest with line segments (array).mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
). The dimension in which the stacked rectangles will be positioned.idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension. Will be used to compute proper origin and span of the bar if the dimension is horizontal or the width of each individual group if the dimension is vertical.idVerticalAxis
- the ID of the axis defining thevertical
dimension. Will be used to compute proper origin and span of the bar if the dimension is vertical or the width of each individual group if the dimension is horizontal.normalValue
- value to position the colorBar in the normal (numerical) axis. The value must be contained within the linear axis domain.
NOTE
idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See axes for more info.
Optional properties
- trackByKey - define this function to let D3 know which property of your data will be used to track changes in it.
To set the lines width and the dots size, you'll need to set three different parameters:
lineWidth - defines the span of the line segment in the normal dimension. The span in the group
mainDimension
is computed just using the value associated to that item in the corresponding axis.circleRadius - defines the radius of each one of the dots of your data in the main dimension.
circleMargin - defines the amount of margin of each one of the dots of your data. Take into account that the value you give to this margin will be computed twice to get the segment width and the total size of the circle. (i.e: If you define a circle with a radius of
2
and margin of3
, the total size of the circle plus its margins will be10
)
The three of these parameters can be expressed either in absolute or natural units:
- Absolute means in the same units as the underlying SVG coordinate space. You can think of this as just pixels (although they are not strictly just pixels and they might not directly translate 1:1 to screen pixels).
- Natural means in the same units as the axis used for the main dimension,
except for
lineWidth
, which is relative to the normal dimension. For instance, if you have an axis of seconds, then anaturalOffset
ofN
is an offset ofN
seconds. If the axis are categories then the absolute value for an offset ofN
is the absolute value forN
categories.
You can choose either absolute or natural values for lineWidth, circleRadius and circleMargin independently. Take into account though, that for ease of use, if you choose to use circleRadius in absolute units, you will need to specify the margin also in absolute units. If you happen to choose circleRadius and naturalCircleMargin, the chart validator will throw an error.
There are 2 exclusive properties available to customize the lineWidth:
lineWidth
- if you want to use absolute units.lineNaturalWidth
- if you want to use absolute units.
There are 2 exclusive properties available to customize the circleRadius:
circleRadius
- if you want to use absolute units.circleNaturalRadius
- if you want to use natural units.
There are 2 exclusive properties available to customize the circleMargin:
circleMargin
- if you want to use absolute units.circleNaturalMargin
- if you want to use absolute units.
Note: You can't set both
lineWidth
andlineNaturalWidth
,circleRadius
andcircleNaturalRadius
, orcircleMargin
andcircleNaturalMargin
. Doing so will throw an invalid config error.
Examples
Horizontal line segments chart
Vertical line segments chart
Anchored shapes charts
Anchored shapes charts are collections of shapes that are tied to a certain axis. This chart can be used in combination with GeoChartLineSegments to compare several values across an axis, each shape being the value that is being represented as the desired shape.
To add anchored shapes groups to a chart, add an array to
anchoredShapesGroups
key of GeoChart's config. Each item of the
array must be an object with the following…
Required properties
data
- array of objects, each one representing a single shape that will be distributed across the axis.mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
). The dimension in which the stacked rectangles will be positioned.idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension. Will be used to compute proper origin and span of the bar if the dimension is horizontal or the width of each individual group if the dimension is vertical.idVerticalAxis
- the ID of the axis defining thevertical
dimension. Will be used to compute proper origin and span of the bar if the dimension is vertical or the width of each individual group if the dimension is horizontal.normalValue
- value to position the colorBar in the normal (numerical) axis. The value must be contained within the linear axis domain.getAnchorPosition
- function to set the shape either on top/left (leading
) or at the bottom/right (trailing
) of the axis. Should return a value of named exportDIMENSIONS.ANCHORED_POSITIONS_1D
.getShapeSize
- function to get the dimensions (width/height) of the desired shape.getShapePath
- function to create the path of the shape. The returned value of this function should be valid as input forsvg
polygon data.
NOTE
idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See Axes for more info.
Optional properties
Offset defines the translation in the normal dimension that must be applied to the shapes in order to not overlap with the axis they're been positioned. (Can be set using natural units)
text object takes a function (content) that lets you shape the format of each one of the labels that will be tied to your shapes. The function should return an array of objects, each one with the properties
text
andcssClass
.trackByKey Define this function to let D3 know which property of your data will be used to track changes in it.
There are 2 exclusive properties available to customize the offset:
offset
- if you want to use absolute units.naturalNormalOffset
- if you want to use natural units.
NOTE
You can't set both offset
and naturalNormalOffset
.
Doing so will throw an invalid config error.
Examples
Horizontal anchored shapes with texts
Horizontal anchored shapes with line segments
Pie charts
Required properties
data
- collection being displayed (array).keyForValues
- the key in each chart item where the value for this axis is stored.
Optional properties
Optionally you can configure the pie with an inner radius and an outer radius. These properties are useful to create different variations of a pie chart, from a full pie chart to a donut chart.
innerRadius
-[0-1]
defines the inner radius factor of the pie being0
the default value and1
the maximum chart radius.outerRadius
-[0-1]
defines the outer radius factor of the pie being1
the default value as the maximum radius allowed by the chart height/width, and0
the minimum chart radius.
Tooltips
Each slice can customize the tooltip displayed when it's hovered by setting the
key tooltip
. This key must store an object with the following shape:
content
- required. Function that takes as parameters the item corresponding to the bar being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each slice can customize its CSS classes by setting a function for key cssClasses
.
This functions takes as parameters the array of classes that would be set by
default, the item corresponding to the slice being customized and its position
inside the data array.
Examples
Simple pie chart
Stacked bar charts
Stacked bar charts are collections of grouped items within a bar chart item which are displayed as rectangles in a 2-dimensional grid. An arbitrary amount of different collections of items can be displayed using stacked bar charts, each of those collections are called groups.
Required properties
Each group requires these properties:
data
- collection being displayed (array).mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
). The dimension in which the rectangle will grow depending on the value.idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension. Will be used to compute proper origin and span of the bar if the dimension is horizontal or the width of each individual group if the dimension is vertical.idVerticalAxis
- the ID of the axis defining thevertical
dimension. Will be used to compute proper origin and span of the bar if the dimension is vertical or the width of each bar if the dimension is horizontal.
NOTE
idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See Axes for more info.
Optional properties
Optionally you can configure each group with a width. This is useful when you want to display multiple collections which have repeated items for the normal dimension.
TIP
Normal dimension is the dimension perpendicular to the group's mainDimension
.
For instance, if you set mainDimension
to horizontal
then the
normal dimension will be vertical
.
To allow maximum flexibility GeoChart
does not prevent overlaps. To prevent
stacked bars from different groups from overlapping you'll have to set a width.
- Width defines the span of the rectangles of a bar in the normal dimension. The
span in the group
dimension
is computed just using the value associated to that item in the corresponding axis.
This property can be expressed either in absolute or natural units:
- Absolute means in the same units as the underlying SVG coordinate space. You can think of this as just pixels (although they are not strictly just pixels and they might not directly translate 1:1 to screen pixels).
- Natural means in the same units as the axis used for the normal dimension.
For instance, if you have an axis of seconds, then a
naturalWidth
ofN
is a width ofN
seconds. If the axis are categories then the absolute value for width ofN
is the absolute value forN
categories.
There are 2 exclusive properties available to customize the width:
width
- if you want to use absolute units.naturalWidth
- if you want to use natural units.
NOTE
You can't set both width
and naturalWidth
. Doing so will throw an invalid config error.
Tooltips
Each stacked bar can customize the tooltip displayed when it's hovered by setting the
key tooltip
. This key must store an object with the following shape:
content
- Required. Function that takes as parameters the item corresponding to the stacked bar being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- Optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each stacked bar can customize its CSS classes by setting a function for key cssClasses
.
This function takes as parameters the array of classes that would be set by
default, the item corresponding to the stacked bar being customized and its position
inside the data array.
Examples
Vertical stacked bar chart
Horizontal stacked bar chart
Quadrants
Use this component to represent 2 lines separating the chart into 4 quadrants, and name these 4 quadrants.
To add quadrant groups to a chart, add an array to quadrantGroups
key of GeoChart's config. Each item of the array must be an object with the following:
Required properties
horizontalAxisConfig
- horizontal axis config of the chart (see axes config), which will create the vertical line of the quadrant.verticalAxisConfig
- vertical axis config of the chart (see axes config), which will create the horizontal line of the quadrant.horizontalThreshold
- relative position of the vertical quadrant line on the horizontal axis of the chart (must be withinhorizontalAxisConfig
's domain). When no threshold is defined, the line isn't shown.verticalThreshold
- relative position of the horizontal quadrant line on the vertical axis of the chart (must be withinverticalAxisConfig
's domain). When no threshold is defined, the line isn't shown.
Optional properties
quadrantTopLeftName
- name of the top left quadrant (to be displayed on the top left corner of the chart).quadrantTopRightName
- name of the top right quadrant (to be displayed on the top right corner of the chart).quadrantBottomLeftName
- name of the bottom left quadrant (to be displayed on the bottom left corner of the chart).quadrantBottomRightName
- name of the bottom right quadrant (to be displayed on the bottom right corner of the chart).fontSize
- size of the names of the quadrant. It should be a number, that will then be displayed in pixels.
Tooltips
Each label and each quadrant line can customize the tooltip displayed when it's hovered by setting the key tooltip
. This key must store an object with the following shape:
content
- Required. Function that takes as parameters the item corresponding to the label or axis being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- Optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each quadrant group can customize its CSS classes by setting a function for key cssClasses
. (Use this for give a custom radius or color to each represented group).
This function takes as parameters the array of classes that would be set by
default, the item corresponding to the scatter plot group being customized and its position inside the data array.
Examples
Quadrant with tooltip
Quadrant with guidelines and categorical axis
One line quadrant with tooltip
Scatter Plot charts
Use this chart to represent values related to two different numerical variables. The position of each dot represents a single value of your data. This chart is designed to represent relationships between each variable of each one of the axes.
To add scatter plot groups to a chart, add an array to scatterPlotGroups
key of GeoChart's config. Each item of the array must be an object with the following:
Required properties
data
- array of objects, each one representing an item with two values that will be converted intox, y
point coordinates across the axes.mainDimension
- a value ofDIMENSIONS.DIMENSIONS_2D
named export (eitherhorizontal
orvertical
).idHorizontalAxis
- the ID of the axis defining thehorizontal
dimension.idVerticalAxis
- the ID of the axis defining thevertical
dimension.
NOTE
Note: idHorizontalAxis
and idVerticalAxis
must be IDs of registered axes.
See axes for more info.
Optional properties
getRadius
- function that gives the radius in pixels of each one of the dots of the graph. If no width is provided, a default radius of2px
will be applied.getFillColor
- function that gives the color in which each dot of the graph should be displayed.getOpacity
- function that gives the opacity with which each dot of the graph should be displayed.groupKey
- property of your data that will be used to compute the radius of each one of the dots.onDotClick
- function executed when clicking on a dot. Only one dot can be clicked at the same time. When unclicking a dot, the function is executed with parameters (null
,null
)blockMouseEvents
- boolean that blocks changes on the dot when having mouveover, mouseout and click events
TIP
If blockMouseEvents
is set to true but you want a specific dot to be already clicked when rendering the graph, you can return CONSTANT.FOCUS_ON_DOT
in the onDotClick
function for this specific dot.
Tooltips
Each scatterPlotGroup can customize the tooltip displayed when hovering on each one of the dots by setting the key tooltip
. This key must store an object with the following shape:
content
- required. Function that takes as parameters the dot corresponding to the scatter plot group being customized and its position inside the data array. It's expected to return a HTML string that will be rendered inside a tooltip.offset
- optional. Function that takes as parameter the event triggering the tooltip and is expected to return an object with anx
and ay
property, both storing numbers that will be used as offset of the tooltip with respect to event coordinates. By default tooltip will be positioned above cursor.
Customizing CSS classes
Each scatter plot group can customize its CSS classes by setting a function for key cssClasses
. (Use this for give a custom radius or color to each represented group).
This function takes as parameters the array of classes that would be set by
default, the item corresponding to the scatter plot group being customized and its position inside the data array.