DataChart

DataChart is in beta mode. We anticipate making API surface changes without changing the grommet major version number. This is to allow broader usage and feedback gathering. In version 2.15.0, the API surface changed, see notes.

DataChart takes an array of objects in data and provides various visualization capabilities on that data. It attempts to default as much as it possibly can to make it easy to get started and then customize later. What follows is some guidance on how to get started and then delve into what DataChart can do.

series

To begin with, give your DataChart some data and set the series property to indicate which properties in the data objects should be used.

54
0
Aug 20
Aug 22

Note that the X and Y axis are defaulted and the dates are automatically formatted based on the granularity given.

chart

Next, we can customize the kind of chart we are looking at.

54
0
Aug 20
Aug 22

axis and guide

Next, we can customize the axis and add guide lines.

$54
$0
Aug 20
Aug 22

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

"start"
"center"
"end"
"stretch"

axis

Whether to show an axis and how it should look. If 'x' or 'y' is a string, it indicates the property to use to determine the values to show. If axis or 'x' is true, DataChart will look for a property called 'date' or 'time' and automatically use that for the x-axis. If DataChart can't find a property to use, it will use the data index for the x-axis. If axis or 'y' is true, DataChart will use the first property in 'series'. 'granularity' indicates how many values to show. 'coarse' granularity shows two values, one at each end. 'fine' granularity shows all x-axis values and 5 y-axis values. 'medium' granularity picks something in between.

{
  "x": [
    true,
    {
      "granularity": [
        "coarse",
        "medium",
        "fine"
      ],
      "property": "date"
    }
  ],
  "y": [
    true,
    {
      "granularity": [
        "coarse",
        "medium",
        "fine"
      ],
      "property": "amount"
    }
  ]
}

bounds

When set to 'align', indicates that the bounds of all series should be aligned. When not set, the bounds of each series property are based solely on the data found for that property.

"align"

chart

How to visualize the data. 'property' indicates which property of the data objects to use. When 'property' is an array, multiple properties are used for a stacked bar chart. If only a string is specified, that is the property to use and all other aspects are defaulted. If 'property' is an object, it specifies a map of properties to graphic aspects: x, y, color, thickness. If 'transform' is specified, it will be used to transform the data value before using it. For example, to convert a data value to a hex color string for the color.

[
  "amount",
  {
    "property": "amount",
    "type": [
      "area",
      "bar",
      "line",
      "point"
    ],
    "color": "graph-1",
    "thickness": "medium",
    "dash": true,
    "round": true
  },
  {
    "property": ["amount", "percent"],
    "type": "bars",
    "thickness": "medium"
  }
]

data

the data set
[
  {
    "date": "2020-05-28",
    "amount": 88,
    "percent": 20
  },
  {
    "date": "2020-05-27",
    "amount": 77,
    "percent": 15
  }
]

detail

Whether to add the ability to interact with the chart via mouse or keyboard to show details on specific values in the chart. It shows all properties specified in 'series', using any 'render' functions therein.

truefalse

gap

The spacing between the axes and the Charts.
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"

gridArea

The name of the area to place this inside a parent Grid.

"a parent grid area name"

guide

Whether to put guidelines underneath the chart graphics. See the description of 'granularity' under 'axis'.

truefalse
{
x:
"boolean"
{
granularity:
"coarse""medium""fine"
}
y:
"boolean"
{
granularity:
"coarse""medium""fine"
}
}

legend

Whether to include a legend
truefalse

margin

The amount of margin around the component. An object can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.

"xsmall"
"small"
"medium"
"large"
"xlarge"
{
  "vertical": "...",
  "horizontal": "...",
  "top": "...",
  "bottom": "...",
  "left": "...",
  "right": "..."
}

pad

Spacing around the outer edge of the drawing coordinate area for the graphic elements to overflow into.

"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"

series

Describes which parts of the 'data' are of interest and how to handle them. 'property' indicates which property of the 'data' objects this series refers to. 'label' indicates how to label the series in a legend or hover details. 'prefix' and 'suffix' are applied to the data values shown in an axis, legend, or details. 'render' allows custom rendering of the data value. 'render' is called with: (value, datum, property) => { return < />; }

[
  "propertyName",
  {
    "label": "Property Label",
    "prefix": "$",
    "property": "propertyName",
    "render": "(value, datam, dataIndex) => element",
    "suffix": "%"
  }
]

size

The size of the Charts. This does not include the axes and any gap. It is passed through to the underlying Chart.

"fill"
{"height": "...", "width": "..."}