Geoblink Design System

GeoChart Ready 9.4.0+

GeoChart 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 with top, right, bottom and left 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 be SCALE.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 an start and an end 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 usually 0 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 this valueForOrigin. If you want to represent temperatures in Celsius degrees this valueForOrigin would probably by 0 but if you want to use Fahrenheit degrees it would be 32.

Example

{
  "type": "linear",
  "domain": {
    "start": -273.15,
    "end": 10000
  },
  "valueForOrigin": 0
}

Logarithmic scales

Almost identical to linear scales, but:

  • type - must be SCALE.SCALE_TYPES.logarithmic.
  • domain - it's lowest end must be > 0.
  • base - (optional) the base of the logarithm, defaults to 10.

Example

{
  "type": "logarithmic",
  "domain": {
    "start": 1,
    "end": 1024
  },
  "valueForOrigin": 1,
  "base": 2
}

Categorical scales

Similar to linear scales, but:

  • type - must be SCALE.SCALE_TYPES.categorical.
  • domain - must be an array of values which can be either strings or numbers.
  • valueForOrigin - must be one of the values of domain 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 be SCALE.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 an start and an end property, both of them dates. A domain may be decreasing.
  • valueForOrigin - must be one of the values of domain array.

Optional properties

  • nice - function that will modify the domain to one that the ticks fit nicely in the graph. Must be one of SCALE.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 of AXIS.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 to AXIS.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 of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical). The dimension in which the rectangle will grow depending on the value.
  • idHorizontalAxis - the ID of the axis defining the horizontal dimension. Will be used to compute proper origin and span of the bar the horizontal.
  • idVerticalAxis - the ID of the axis defining the vertical 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 of N is an offset of N seconds. If the axis are categories then the absolute value for an offset of N is the absolute value for N 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 an x and a y 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. Each data entry must have a value for the key used by the axis referenced in idVerticalAxis and idHorizontalAxis (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 with top, right, bottom and left keys, whose values are numbers. It is the padding to be applied to the text.
  • margin - (optional) object with top, right, bottom and left keys, whose values are numbers. It is the margin to be applied to the text container. You can combine padding and margin 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 of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical). The dimension in which the stacked rectangles will be positioned.
  • idHorizontalAxis - the ID of the axis defining the horizontal 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 the vertical 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 of N is an offset of N seconds. If the axis are categories then the absolute value for an offset of N is the absolute value for N 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

Horizontal color bar with width and highlightedWidth values

Horizontal color bar with naturalWidth and naturalHighlightedWidth values

Vertical color bar with width and highlightedWidth values

Vertical color bar with naturalWidth and naturalHighlightedWidth values

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 into x, y point coordinates across the axes.
  • mainDimension - a value of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical).
  • idHorizontalAxis - the ID of the axis defining the horizontal dimension.
  • idVerticalAxis - the ID of the axis defining the vertical 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 of 2px 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 of 2px 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 to d3.curveLinear.
  • trackByKey - define this function to let D3 know which property of your data will be used to track changes in it.
  • isInteractive - set this flag to false to disable interactions when hovering the mouse over a line group, defaults to true.

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 an x and a y 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 of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical). The dimension in which the stacked rectangles will be positioned.
  • idHorizontalAxis - the ID of the axis defining the horizontal 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 the vertical 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 of 3, the total size of the circle plus its margins will be 10)

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 a naturalOffset of N is an offset of N seconds. If the axis are categories then the absolute value for an offset of N is the absolute value for N 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 and lineNaturalWidth, circleRadius and circleNaturalRadius, or circleMargin and circleNaturalMargin. 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 of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical). The dimension in which the stacked rectangles will be positioned.
  • idHorizontalAxis - the ID of the axis defining the horizontal 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 the vertical 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 export DIMENSIONS.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 for svg 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 and cssClass.

  • 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 being 0 the default value and 1 the maximum chart radius.

  • outerRadius - [0-1] defines the outer radius factor of the pie being 1 the default value as the maximum radius allowed by the chart height/width, and 0 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 an x and a y 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 of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical). The dimension in which the rectangle will grow depending on the value.
  • idHorizontalAxis - the ID of the axis defining the horizontal 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 the vertical 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 of N is a width of N seconds. If the axis are categories then the absolute value for width of N is the absolute value for N 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 an x and a y 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 within horizontalAxisConfig'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 within verticalAxisConfig'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 an x and a y 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 into x, y point coordinates across the axes.
  • mainDimension - a value of DIMENSIONS.DIMENSIONS_2D named export (either horizontal or vertical).
  • idHorizontalAxis - the ID of the axis defining the horizontal dimension.
  • idVerticalAxis - the ID of the axis defining the vertical 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 of 2px 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 an x and a y 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.

Examples

Scatter Plot with data

Scatter Plot with data groups by color

Scatter Plot with data groups by radius with click event

Scatter Plot with data groups in quadrants with click event

Scatter Plot focused on a dot