@influxdata/giraffe

v2.38.1

Published

a year ago

[![Slack Status](https://img.shields.io/badge/slack-join_chat-white.svg?logo=slack&style=social)](https://www.influxdata.com/slack)

Downloads

3,227

Giraffe

A React-based visualization library powering the data visualizations in InfluxDB 2.0 UI.

Demos

See the visualizations in action using Storybook

Quick Start

Giraffe can be used in a simple index.html page without any advanced configuration. Even though Giraffe is designed to work with React apps, you won't need React or Node.js to do the quickstart below.

In this quickstart, we're going to build a simple line graph using Giraffe in a single index file. All you'll need is a text editor.

Set up your index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Giraffe</title>
</head>

<body id="home">
  <main id="root"></main>
</body>
</html>

Save this file as index.html.

Add script imports of React, React-DOM, and Giraffe to the bottom of the head section.

  <script crossorigin src="https://unpkg.com/react@17/umd/react.development.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>
  <script crossorigin src="https://unpkg.com/@influxdata/giraffe"></script>
</head>

Wire up a simple React element. Add a script tag under main in the body of the html document, and then render a simple element onto the page using React.

  <main id="root"></main>
  <script type="text/javascript">
    ReactDOM.render(
      React.createElement('h1', null, 'Hello World'),
      document.getElementById('root')
    );
  </script>
</body>

Open index.html in a browser. You should see a header with Hello World as the text.

Create a wrapper element for the Giraffe Plot we'll be rendering into. Add it to the script tag under root:

<main id="root"></main>
  <script type="text/javascript">
    class PlotRenderer extends React.Component {
      render() {
        const style = {
          width: "calc(70vw - 20px)",
          height: "calc(70vh - 20px)",
          margin: "40px",
        };
        return React.createElement('div', {style}, 'Giraffe Plot Goes Here');
      }
    }
  <script>

And have React render that element. Change the ReactDOM.render call to:
```
ReactDOM.render(
  React.createElement(PlotRenderer, null, null),
  document.getElementById('root')
);
```
Open up index.html. You should see Giraffe Plot Goes Here where it used to say Hello World.
Our last step is to create some fake data and then draw that fake data into a plot. First, we'll create a configuration object that tells Giraffe to render a line graph. In the render method of PlotRenderer, add the following code:
```
const lineLayer = {
  type: "line",
  x: "_time",
  y: "_value"
};
```

Let's create the fake data. After the lineLayer code, add the following:

const table = Giraffe.newTable(3)
  .addColumn('_time', 'dateTime:RFC3339', 'time', [1589838401244, 1589838461244, 1589838521244])
  .addColumn('_value', 'double', 'number', [2.58, 7.11, 4.79]);

Now we'll combine them into a config object. Add this after the line that creates table:
```
const config = {
  table,
  layers: [lineLayer]
};
```
Finally, let's create a Plot with this configuration and render it. Below the line that creates config in the render method, add the following code:
```
const SimplePlot = React.createElement(Giraffe.Plot, {config}, null);
return React.createElement('div', {style}, SimplePlot);
```
And there you have it.

Here is the full index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Giraffe</title>
  <script crossorigin src="https://unpkg.com/react@17/umd/react.development.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>
  <script crossorigin src="https://unpkg.com/@influxdata/giraffe"></script>
</head>

<body id="home">
  <main id="root"></main>
  <script type="text/javascript">
    class PlotRenderer extends React.Component {
      render() {
        const style = {
          width: "calc(70vw - 20px)",
          height: "calc(70vh - 20px)",
          margin: "40px",
        };

        const lineLayer = {
          type: "line",
          x: "_time",
          y: "_value"
        };

        const table = Giraffe.newTable(3)
          .addColumn('_time', 'dateTime:RFC3339', 'time', [1589838401244, 1589838461244, 1589838521244])
          .addColumn('_value', 'double', 'number', [2.58, 7.11, 4.79]);

        const config = {
          table,
          layers: [lineLayer]
        };

        const SimplePlot = React.createElement(Giraffe.Plot, {config}, null);
        return React.createElement('div', {style}, SimplePlot);
      }
    }

    ReactDOM.render(
      React.createElement(PlotRenderer),
      document.getElementById('root')
    );
  </script>
</body>
</html>

Examples Using Flux

1. Generating the table through a Flux result

When generating the table through a Flux result:

call the fromFlux utility function on the CSV generated by Flux
get the table in the returned object from calling fromFlux

Here is an example of turning a result in comma separate values (CSV) from Flux into a table and rendering it without optional properties:

2. Using CSV from a Flux query

When using the comma separated values (CSV) from the Flux query as the fluxResponse property:

Config

<Plot> requires a config prop which is an object with properties that serve three purposes:

appearance customization for sizing and framing
data store, getters and setters, and plot-type specific options
legend and tooltip customization

Appearance properties

width: number. Optional. The width in CSS px of the Plot. Includes the space to the left of the axes surrounding the ticks, tick labels, and axis labels. When not specified, the width of <Plot>'s parent element will determine the width.
height: number. Optional. The height in CSS px of the Plot. Includes the space below the axes surrounding the ticks, tick labels, and axis labels. When not specified, the height of <Plot>'s parent element will determine the height.
gridColor: string. Optional. The CSS color value of the grid lines. Applies to the inner horizontal and vertical rule lines. Excludes the axes and the border around the graph.
cursor: string. Optional. Defaults to "crosshair" when excluded. The CSS cursor property when the cursor is inside the rendered area of <Plot>.
gridOpacity: number. Optional. Recommendation: do not include. Defaults to 1 when excluded. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the grid lines. Applies to the inner horizontal and vertical rule lines. Excludes the axes and the border around the graph.
showAxes: boolean. Optional. Recommendation: do not include. Defaults to true when excluded. Exception: not configurable and always false for Gauge, RawFluxDataTable, TableGraph. Indicates whether Plot axes should be visible. Applies to both x-axis and y-axis simultaneously.
axisColor: string. Optional. The CSS color value of the axes and the border around the graph. Excludes the inner horizontal and vertical rule lines.
axisOpacity: number. Optional. Recommendation: do not include. Defaults to 1 when excluded. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the axes and the border around the graph. Excludes the inner horizontal and vertical rule lines.
xTicks: array[number, ...]. Optional. An array of values representing tick marks on the x-axis. Actual data values and axis scaling may cause Plot to not render all of the given ticks, or Plot rendering may extend beyond all of the rendered ticks. When this option is included, xTotalTicks, xTickStep, xTickStart are ignored.
xTotalTicks: number. Optional. Ignored when xTicks is specified. A number representing the maximum possible number of ticks to generate on the x-axis. Uses the xTickStep as the tick interval if also included. Otherwise the tick interval is taken from dividing the length of the rendered domain by this number. The actual number of rendered ticks may be less than this number due to the size of the tick interval.
xTickStep: number. Optional. Ignored when xTicks is specified. A number representing the tick interval for the x-axis. May be negative.
xTickStart: number. Optional. Ignored when xTicks is specified. A number representing a value less than or equal to the first tick on the x-axis. This number will determine the placement of all subsequent ticks. It and any subsequent ticks will be rendered only if they fall within the domain. This number is the value of the first tick when it is in the domain, and at least one of xTickStep or xTotalTicks is included.
yTicks: array[number, ...]. Optional. An array of values representing tick marks on the y-axis. Actual data values and axis scaling may cause Plot to not render all of the given ticks, or Plot rendering may extend beyond all of the rendered ticks. When this option is included, yTotalTicks, yTickStep, yTickStart are ignored.
yTotalTicks: number. Optional. Ignored when yTicks is specified. A number representing the maximum possible number of ticks to generate on the y-axis. Uses the yTickStep as the tick interval if also included. Otherwise the tick interval is taken from dividing the length of the rendered domain by this number. The actual number of rendered ticks may be less than this number due to the size of the tick interval.
yTickStep: number. Optional. Ignored when yTicks is specified. A number representing the tick interval for the y-axis. May be negative.
yTickStart: number. Optional. Ignored when yTicks is specified. A number representing a value less than or equal to the first tick on the y-axis. This number will determine the placement of all subsequent ticks. It and any subsequent ticks will be rendered only if they fall within the domain. This number is the value of the first tick when it is in the domain, and at least one of yTickStep or yTotalTicks is included.
tickFont: string. Optional. The CSS font value for the styling of the tick labels and axis labels.
tickFontColor: string. Optional. The CSS color value of the tick labels and axis labels.
valueFormatters: object. Optional. An object containing column keys and their corresponding functions that format data for that column type. Each function takes a data value as the first argument, and an optional second argument as an options object. Returns a formatted string for that data value. For example:
xAxisLabel: string. Optional. Uses tickFont, tickFontColor. Name to display below the x-axis.
yAxisLabel: string. Optional. Uses tickFont, tickFontColor. Name to display to the left of the y-axis.

Data properties

There are three ways to pass in data to Giraffe depending on the layer (graph) type:

Data Property Name | SimpleTable | TableGraph | All Other Layers --------------------|------------------------|------------|------------------ fluxResponse | optional | required | optional fromFluxResult | optional (preferred) | not used | not used table | not used | not used | optional (preferred)

fluxResponse: String. Required for TableGraph layer. Optional for all other layers. The unparsed string of comma separated values returned from a Flux query representing the data to be visualized. For TableGraph, it is required, as it is the only property that represents the data. For SimpleTable, this property is ignored when fromFluxResult is present, as fromFluxResult takes precendence, For all other layer types, this property is ignored when table is present, as table takes precendence.
fromFluxResult: Object. Optional and used only by the SimpleTable layer type. An object containing the properties of the result of parsing fluxResponse. Using this property prevents SimpleTable from unnecessarily re-parsing the fluxResponse. When both are missing, config will create an empty data set. Ignored by all other layer types, see below.
table: Object. Optional. The data structure for a layer obtained from parsing a fluxResponse. Not used by the SimpleTable and TableGraph layer types (SimpleTable and TableGraph, see above). When present, overrides fluxResponse. When missing, config will look for fluxResponse and parse it to create the table. When both are missing, config will create an empty table. This property is a data object produced by Giraffe's utility functions. Houses the data and getters and setters for that data, for the <Plot>.
- the table property of the return value from the fromFlux utility function.
- the return value from the fromRows utility function.
- the return value from the newTable utility function.
layers: array[Object, ...]. Required. An array of LayerConfig objects. These objects are customizations specific to a type of <Plot>. Currently, Giraffe supports only one pre-defined <Plot> type per graph with any number of "custom layers". Custom layers are not pre-defined in Giraffe, but created through a callback render function in the configuration.
xScale: "linear" | "log". Optional. Sets the scaling function to be used on the x-axis internally by Giraffe to generate values for resources, such as tick marks.
- "linear" scaling means the same distance between ticks represents the same increase in value.
- "log" (logarithmic) scaling means the same distance between ticks can represent an exponential increase in value, used as a way to display data with a very wide range of values in a compact space.
yScale: "linear" | "log". Optional. Sets the scaling function to be used on the y-axis internally by Giraffe to generate values for resources, such as tick marks.
- "linear" scaling means the same distance between ticks represents the same increase in value.
- "log" (logarithmic) scaling means the same distance between ticks can represent an exponential increase in value, used as a way to display data with a very wide range of values in a compact space.
xDomain: array[min, max]. Optional. When used must also include the callback functions onSetXDomain and onResetXDomain; or include includeXDomainZoom with any of the two callback functions. The x domain of the plot can be explicitly set with numbers denoting a minimum and a maximum value for the x-axis. If this option is passed, both min and max are required to be numbers, making the <Plot> operate in a "controlled" mode, where it always uses the passed x domain. Any brush interaction with the <Plot> that should change the x domain will use Giraffe's built-in brush handler if includeXDomainZoom is true. Additionally, the onSetXDomain callback function will be invoked if provided. Double clicking the plot will call Giraffe's built-in reset handler if includeXDomainZoom is true. Additionally, the onResetXDomain callback function will be invoked if provided. If the xDomain option is not passed, then the component is "uncontrolled". It will compute, set, and reset the xDomain automatically.
includeXDomainZoom: boolean. Optional, for use with xDomain. See above regarding xDomain.
onSetXDomain: function(array[min, max]). Optional, for use with xDomain. See above regarding xDomain.
onResetXDomain: function(). Optional, for use with xDomain. See above regarding xDomain.
yDomain: array[min, max]. Optional. When used must also include the callback functions onSetYDomain and onResetYDomain; or include includeYDomainZoom with any of the two callback functions. The y domain of the plot can be explicitly set with numbers denoting a minimum and a maximum value for the y-axis. If this option is passed, both min and max are required to be numbers, making the <Plot> operate in a "controlled" mode, where it always uses the passed y domain. Any brush interaction with the <Plot> that should change the y domain will use Giraffe's built-in brush handler if includeYDomainZoom is true. Additionally, the onSetYDomain callback function will be invoked if provided. Double clicking the plot will call Giraffe's built-in reset handler if includeYDomainZoom is true. Additionally, the onResetYDomain callback function will be invoked if provided. If the yDomain option is not passed, then the component is "uncontrolled". It will compute, set, and reset the yDomain automatically.
includeYDomainZoom: boolean. Optional, for use with yDomain. See above regarding yDomain.
onSetYDomain: function(array[min, max]). Optional, for use with yDomain. See above regarding yDomain.
onResetYDomain: function(). Optional, for use with yDomain. See above regarding yDomain.

Legend and Tooltip properties

legendBackgroundColor: string. Optional. Defaults to #0f0e15 when excluded. The CSS color value of the background in the legend and tooltip. May be overriden.
legendBorder: string. Optional. The CSS border value for the styling of the border around the legend and tooltip. May be overriden.
legendColorizeRows: boolean. Optional. Defaults to true when excluded. Toggles the use of colors for the rows in the legend and tooltip. When true the rows will use colors from the color scheme in the rendered graph. When false the rows will use the legendFontBrightColor and include small dots of color in the color scheme of the rendered graph. May be overriden.
legendColumns: array[string, ...]. Optional. When included, this array will determine which column names that should be included in the legend and tooltip. If this option is included as an empty array, the legend and tooltip will be empty. May be overriden.
legendCrosshairColor: string | Object. Optional. The CSS color value or styling of the vertical crosshair line through the Plot at where the mouse is hovering, defined as a CanvasRenderingContext2D strokeStyle.
legendHide: boolean. Optional. Defaults to false when not included. true means the legend and tooltip will not be rendered. false means the legend and tooltip will be rendered. May be overriden.
legendFont: string. Optional. Defaults to '10px monospace' when excluded. The CSS font value for the styling of the legend and tooltip. May be overriden.
legendFontBrightColor: string. Optional. Defaults to #f6f6f8 when excluded. The CSS color value of any text that is not a column header or in a row inside the legend or tooltip. May be overriden.
legendFontColor: string. Optional. Defaults to #bec2cc when excluded. The CSS color value of the column headers in the legend or tooltip. The rest of the content will use the color scheme set by the LayerConfig's colors options. May be overriden.
legendMessage: string. Not used. Reserved for future implementation. A string to display in the legend and tooltip. Does not affect the renderable content in a legend or tooltip, such as column names and data. May be overriden.
legendOpacity: number. Optional. Defaults to 1.0 when excluded. The CSS opacity of the legend and tooltip. 0 means the legend and tooltip are invisible, while 1.0 means the legend and tooltip are solid and their content may cover anything underneath. May be overriden.
legendOrientationThreshold: number. Optional. Defaults to undefined when excluded. The number of columns in the legend that will determine the direction of columns in the legend. When undefined or when the total number of columns is less than or equal to it, the columns in the tooltip will display horizontally. When the total number of columns is greater, the columns will display vertically. May be overriden.
staticLegend: Object. Optional. Must be included to show a static legend. May be an empty object. An object with properties that override the legend properties and apply only to the static legend that is always visible. Has a few properties that are unique to the static legend, such as heightRatio which sets the height of the static legend. Properties are:
- backgroundColor: string. Optional. Defaults to #0f0e15 when excluded. The CSS color value of the background in the static legend.
- border: string. Optional. The CSS border value for the styling of the border around the static legend.
- colorizeRows: boolean. Optional. Defaults to true when excluded. Toggles the use of colors for the rows in the static legend. When true the rows will use colors from the color scheme in the rendered graph. When false the rows will use the fontBrightColor and include small dots of color in the color scheme of the rendered graph.
- columns: array[string, ...]. Optional. When included, this array will determine which column names that should be included in the static legend. If this option is included as an empty array, the static legend will be empty.
- crosshairColor: string | Object. Optional. Generally not used, unless legendCrosshairColor is missing, then this property has the same effect. The CSS color value or styling of the vertical crosshair line through the Plot at where the mouse is hovering, defined as a CanvasRenderingContext2D strokeStyle.
- cursor: string | Object. Optional. The CSS cursor property of the mouse when inside the area of the static legend.
- hide: boolean. Optional. Defaults to false when not included. true means the static legend will not be rendered. false means the static legend will be rendered.
- font: string. Optional. Defaults to '10px monospace' when excluded. The CSS font value for the styling of the static legend.
- fontBrightColor: string. Optional. Defaults to #f6f6f8 when excluded. The CSS color value of any text that is not a column header or in a row inside the static legend.
- fontColor: string. Optional. Defaults to #bec2cc when excluded. The CSS color value of the column headers in the static legend. The rest of the static legend will use the color scheme set by the LayerConfig's colors options.
- heightRatio: number. Optional. Defaults to 0.2 when not included. A fraction expressed as a decimal to indicate the height of the static legend which is a retangular box directly beneath the graph and axes. May be between 0 and 1 non-inclusive. Values outside of this range are considered 0. Must be non-zero for static legend to be visible (have height).
- layer: number. Optional. Defaults to 0 (the first layer) when not included. The index of the layer in the layers array that will be displayed in the static legend. The static legend will only display data for a single layer.
- message: string. Not used. Reserved for future implementation. A string to display in the static legend. Does not affect the renderable content in the static legend, such as column names and data.
- opacity: number. Optional. Defaults to 1.0 when excluded. The CSS opacity of the static legend.
- orientationThreshold: number. Optional. Defaults to undefined when excluded. The number of columns in the legend that will determine the direction of columns in the legend. When undefined or when the total number of columns is less than or equal to it, the columns in the tooltip will display horizontally. When the total number of columns is greater, the columns will display vertically.
- renderEffect: function(object). Optional. Defaults to an empty function (no operation) when excluded. A callback function that executes after each render. The purpose is to allow the consumer to adjust config properties based on certain aspects of the static legend. An example would be auto-adjusting the height of the static legend to fit its contents. This function is given an options object as the argument which has the following properties:
  - totalHeight: number. The height of the <Plot> including the static legend.
  - staticLegendHeight: number. The height of the static legend.
  - legendDataLength: number. The total number of "fill" columns plus any additional columns added by the static legend to be rendered.
  - lineCount: number. The total number of rows, when in a horizontal orientation, excluding the header row. Or the total number of columns, when in a vertical orientation, excluding the header column.
  - lineSpacingRatio: number. The relative unit length in em of the spacing between rows. When in a horizontal orientation, this number in em is equal to the spacing. When in a vertical orientation, the spacing is twice this number in em.
  - padding: number. The default padding added around all of the content in the static legend. Does not include any padding that is applied by style or any other custom styling.
  - headerTextMetrics: Object. An object whose properties are estimates of the width and height in the header row (horizontal orientation) or header column (vertical orientation).
  - sampleTextMetrics: Object. An object whose properties are estimates of the width and height of each entry in an example row (horizontal orientation) or example column (vertical orientation).
- style: Object. Optional. An object containing the key-value pairs used for inline styling the class .giraffe-static-legend by using the style property. Primarily used for adjusting margin and padding. May be used to add additional styling to Static Legend, but does not affect the following styles: backgroundColor, border, bottom, color, cursor, font, height, left, opacity, overflow, position, right, top, width.
- valueAxis: _string. Optional. Defaults to 'y' when not included. Valid values are either 'x' or 'y'. This is to set where the 'values' that are displayed in the tooltip come from (which axis, x or y)
- widthRatio: number. Optional. Defaults to full width when not included. Generally not used and only reserved for future feature implementation. A fraction expressed as a decimal to indicate the width of the static legend which is a retangular box directly beneath the graph and axes. May be between 0 and 1 non-inclusive. Values outside of this range are considered 0. Must be non-zero for static legend to have less than full width of the <Plot>.

Utility Functions

Giraffe comes with utility functions.

fromFlux: function(string). Takes a Flux CSV, converts it, and returns an object that includes Table used in the table property of the config.
fromRows: function([Object, ...], Object). The first argument is an array of objects, each representing a row of data. The optional second argument describes the schema for the data. Returns a Table used in the table property of the config.
newTable: function(number). The argument is a length for a newly created Table with no initial data that allows only columns equal to that length to be added. Returns the created Table.
timeFormatter: function(object). Takes the optional params of locale, format, and hour12. And the required param of timeZone. TimeZone is an option for which timezone you would like the time formatter to return, examples are UTC, or America/Los_Angeles. It will default 24 hour when using UTC, and 12 hours for all others. A full list of compatible time zones IANA Database. Format is for formatting for the standard Date and time formats. Ex: YYYY-MM-DD HH:mm:ss ZZ, or HH:mm a. Hour12 is a boolean value on wether you are in military time(false) or am/pm(true).

LayerConfig

LineLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "line". Required. Specifies that this LayerConfig and <Plot> is a line graph.
- x: string. Required. The column name of the column that should be visualized on the x-axis.
- y: string. Required. The column name of the column that should be visualized on the y-axis.
- fill: array[string, ...]. Optional. An array of column names of column filters that should be visualized. If this option is not included, the data in the graph will be interpreted as belonging to a single column.
- position: "overlaid" | "stacked". Optional. Indicates whether the line graph's lines have no bearing on other lines (overlaid), or the lines are cumulatives of every line below it, ie stacked.
- hoverDimension: "x" | "y" | "xy" | "auto". Optional. Defaults to "auto" when not included. Indicates whether the tooltip should display all data points along an entire axis during mouse hover.
  - "x" means the legend will display all data points along the y-axis that have the same x-axis value
  - "y" means the legend will display all data points along the x-axis that have the same y-axis value
  - "xy" means the legend will display for a single data point nearest the mouse
  - "auto" means "xy" if the legend has more than maxTooltipRows otherwise "auto" means "x"
- maxTooltipRows: number. Optional. Defaults to 24 when not included. The maximum number of data rows to display in the tooltip. Subject to screen size limitations and is not responsive or adaptive. Scrolling not implemented.
- interpolation: string. Optional. Defaults to "linear" when not included. The style of the path between two data points on the same line. For example, "linear" is a straight path between two data points. The options are linear, natural, monotoneX, monotoneY, cubic, step, stepBefore, and stepAfter.
- lineWidth: number. Optional. The CanvasRenderingContext2D lineWidth of each graph line.
- colors: array[string, ...]. Optional. An array of CSS color values used as a gradient to give multiple lines in the graph different colors based on the fill columns.
- shadeBelow: boolean. Optional. Uses colors. Indicates whether the area below each line should be shaded.
- shadeBelowOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the shaded color below each line. No effect when shadeBelow is false or not included.
BandLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "band". Required. Specifies that this LayerConfig and <Plot> is a band chart.
- x: string. Required. The column name of the column that should be visualized on the x-axis.
- y: string. Required. The column name of the column that should be visualized on the y-axis.
- fill: array[string, ...]. Required. An array of column names of column filters that should be visualized.
- hoverDimension: "x" | "y" | "xy" | "auto". Optional. Defaults to "xy" when not included. Indicates whether the tooltip should display all data points along an entire axis during mouse hover.
  - "x" means the legend will display all data points along the y-axis that have the same x-axis value
  - "y" means the legend will display all data points along the x-axis that have the same y-axis value
  - "xy" means the legend will display for a single data point nearest the mouse
  - "auto" means "xy" if the legend has more than maxTooltipRows otherwise "auto" means "x"
- maxTooltipRows: number. Optional. Defaults to 24 when not included. The maximum number of data rows to display in the tooltip. Subject to screen size limitations and is not responsive or adaptive. Scrolling not implemented.
- interpolation: string. Optional. Defaults to "linear" when not included. The style of the path between two data points on the same line. For example, "linear" is a straight path between two data points. The options are linear, natural, monotoneX, monotoneY, cubic, step, stepBefore, and stepAfter.
- lineWidth: number. Optional. The CanvasRenderingContext2D lineWidth of the middle part of each band as identified by the name option.
- colors: array[string, ...]. Optional. An array of CSS color values used as a gradient to give multiple lines in the graph different colors based on the fill columns.
- lineOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the middle part of each band as identified by the name option.
- shadeOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the shaded sections of each band.
- mainColumnName: string. Required. A string indicating the yield name of the line for the middle part of each band. This mainColumnName must match the result in the data. If no matching name within the data is found, that result will not be rendered. Only one yield name can be the mainColumnName per <Plot>.
- upperColumnName: string. Optional. A string indicating the shaded portion of each band that extends above the mainColumnName line.
- lowerColumnName: string. Optional. A string indicating the shaded portion of each band that extends below the mainColumnName line.
ScatterLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "scatter". Required. Specifies that this LayerConfig and <Plot> is a scatter plot.
- x: string. Required. The column name of the column that should be visualized on the x-axis.
- y: string. Required. The column name of the column that should be visualized on the y-axis.
- fill: array[string, ...]. Optional. An array of column names of column filters that should be visualized. If this option is not included, the data in the graph will be interpreted as belonging to a single column.
- colors: array[string, ...]. Optional. An array of CSS color values used as a gradient to give dots in the graph different colors based on the fill columns.
- symbol: array[string, ...]. Optional. An array of columm key names of column filters that should be visualized. Acts like a secondary fill using different symbols for the dots rather than colors. Limited to 6 different symbols. Symbols will repeat above limit.
GeoLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "geo". Required. Specifies that this LayerConfig and <Plot> is a geo plot.
- lat: number. Required. The column name or field that should be used to visualize the data point on the map.
- lon: string. Required. The column name or field that should be used to visualize the data point on the map.
- zoom: number. Required. The number that will determine the zoom of the map.
- allowPanAndZoom: boolean. Required. A boolean field that will display or not display the zoom in/out controls on the map.
- mapStyle: string. Optional. The string will determine the style of the map to use to display the data points.
- detectCoordinateFields: boolean. Required. The boolean is conditioned whether the lat/lon are given as or given as fields. If the lat/lon exist in the _field, then this prop will be true in order to read the lat/lon properly.
- onViewportChange: function(number, number, number). Optional. The library we use to render the map, React leaflet, provides a nice onViewportChanged callback that captures center and zoom changes when using the map.
- onUpdateViewport: function(number, number, number). Optional. This function is passed in if we want to update the viewport when we want to update using the zoom controls on the map.
- onUpdateQuery: function(Object). Optional. This function is used if we want to update the map's sizing based on when the window resizing happens.
- layers: array[Object]. Required. This function is used if we want to update the map's sizing based on when the window resizing happens.
- tileServerConfiguration: Object. Required. Property that allows us to pass in the proper configuration of displaying maps. The configuration includes of the map service url and the key/token.
HistogramLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "histogram". Required. Specifies that this LayerConfig and <Plot> is a histogram.
- x: string. Required. The column name of the column that should be visualized on the x-axis. Note: the y-axis is always the count.
- binCount: number. Optional. Defaults to using Sturges' Formula when not included. The number of buckets or bins on the x-axis. The range of values that fall into each bin depends on the scale and domain of the x-axis.
- fill: array[string, ...]. Optional. An array of column names of column filters that should be visualized. If this option is not included, the data in the graph will be interpreted as belonging to a single column.
- position: "overlaid" | "stacked". Optional. Indicates whether the fill columns of different colors for the same bin should cover each other ("overlaid") or be "stacked" upon each other touching only at the borders. When "overlaid" the covering order follows the same order as found in each column of the data, with the lower indexed values covered by the higher indexed values.
- colors: array[string, ...]. Optional. An array of CSS color values used as a gradient to give bars in each bin different colors based on the fill columns.
- fillOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the shading inside the bins.
- strokeOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the border of the bins. This is very hard to observe with human eyes unless the fillOpacity is near 0.
- strokePadding: number. Optional. The space around all four sides of each bin. The amount of spacing is the width and height used in the CanvasRenderingContext2D rect function.
- strokeWidth: number. Optional. The CanvasRenderingContext2D lineWidth of the border of the bins. This is very hard to observe with human eyes unless the fillOpacity is near 0. A high value for strokeWidth will completely fill the bin with border color at an opacity indicated by strokeOpacity.
MosaicLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "mosaic". Required. Specifies that this LayerConfig and <Plot> is a mosaic.
- x: string. Required. The column name of the column that should be visualized on the x-axis. Note: in the current implementation, this is always _time.
- y: array[string, ...]. Required. An array of column names that groups (or filters) data for the y-axis to visualize against a state or status (fill, see below).
- yLabelColumns: array[string, ...] Required. An array of column names that are used for labeling each tick in the y-axis and the header inside the legend. This allows the y-axis labels and legend header to be less verbose than naming all of the columns that used for y. Does not affect data grouping. This property is a subset of y (see above). Any elements in yLabelColumns that do not appear in y are ignored.
- yLabelColumnSeparator: string. Optional. Defaults to empty string (no separator) when not included. A string given to the CanvasRenderingContext2D.fillText function to use as a separator between the column names of the data for the y-axis.
- fill: array[string]. Required. An array with a single column name that is the state or status being visualized. This property is an array with a single element in order to remain consistent with other LayerConfigs where fill is always an array.
- hoverDimension?: "x" | "y" | "xy" | "auto". Optional. Defaults to "auto" when not included. Indicates whether the tooltip should display all data points along an entire axis during mouse hover.
  - "x" means the legend will display all data points along the y-axis that have the same x-axis value
  - "y" means the legend will display all data points along the x-axis that have the same y-axis value
  - "xy" means the legend will display for a single data point nearest the mouse
  - "auto" means "xy"
- colors: array[string, ...]. Optional. An array of CSS color values used as a gradient to give each mosaic piece in a row (y-axis tick) different colors based on the fill column value.
- fillOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the shading inside the mosaic pieces.
- strokeOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the border of the mosaic pieces. This is very hard to observe with human eyes unless the fillOpacity is near 0.
- strokePadding: number. Optional. The space around all four sides of each mosaic piece. The amount of spacing is the width and height used in the CanvasRenderingContext2D rect function.
- strokeWidth: number. Optional. The CanvasRenderingContext2D lineWidth of the border of the mosaic pieces. This is very hard to observe with human eyes unless the fillOpacity is near 0. A high value for strokeWidth will completely fill the mosaic piece with border color at an opacity indicated by strokeOpacity.
HeatmapLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: "heatmap". Required. Specifies that this LayerConfig and <Plot> is a heatmap.
- x: string. Required. The column name of the column that should be visualized on the x-axis.
- y: string. Required. The column name of the column that should be visualized on the y-axis.
- binSize: number. Optional. The CSS px size of each heat bin. config's width divided by binSize will determine the total number of heat bins along the x-axis. config's height divided by binSize will determine the total number of heat bins along the y-axis.
- colors: array[string, ...]. Optional. An array of CSS color values used as the color scheme in the heatmap. The color in index 0 is used to represent the "cold" area or background of the heatmap. The higher the index, the "hotter" the color will represent on the heatmap.
- fillOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the shading inside the heat bins. Warning: low opacity is difficult to see visually and may be counterproductive for heatmaps.
- strokeOpacity: number. Optional. A value between 0 and 1 inclusive for the CanvasRenderingContext2D globalAlpha of the border of the heat bins. This is very hard to observe with human eyes unless the fillOpacity is near 0.
- strokeWidth: number. Optional. The CanvasRenderingContext2D lineWidth of the border of the bins. This is very hard to observe with human eyes unless the fillOpacity is near 0. A high value for strokeWidth will completely fill the heat bin with border color at an opacity indicated by strokeOpacity.
- strokePadding: number. Optional. The space around all four sides of each heat bin. The amount of spacing is the width and height used in the CanvasRenderingContext2D rect function.
RawFluxDataTableLayerConfig: Object. Maximum one per <Plot>. Uses its own property called files as the data to be rendered. Ignores both tables and fluxResponse from config. Properties are:
- type: 'flux data table'. Required. Specifies that this LayerConfig is a flux data table.
- files: array[string, ...]. Required. The data to be rendered. An array of strings of comma separated values (CSV). Each CSV string can be taken from a Flux response or manually created. At least one string is required. The string cannot not be an empty string nor a string of only empty space(s).
- disableVerticalScrolling: boolean. Optional. Recommendation: do not include. Defaults to false when excluded. Disables the vertical scrollbar for the rendered table.
- parseObjects: boolean. Optional. Defaults to false when excluded. Enables the parsing of JSON objects in the CSV of files so that JSON objects are correctly interpreted when there are commas in the object, and prevents all data from being combined into a single column.
TableGraphLayerConfig: Object. Maximum one per <Plot>. Requires the use of a <HoverTimeProvider> component around the <Plot> and its parent. For example, here is how to properly wrap <Plot> to use render a table:

TableGraphLayerConfig uses the fluxResponse property from config as the data to be rendered. Properties are:

type: 'table'. Required. Specifies that this LayerConfig is a table graph.
timeZone: string. Required. A string representing the desired time zone. Must be an official IANA time zone.
tableTheme: string. Optional. Defaults to 'dark' when excluded. The visual theme for the table graph. Currently, the choices are 'dark' and 'light'.
properties: Object. Required. An object specifying additional options for the table graph. The properties are:
- colors: array[string, ...]. Required. An array of CSS color values used as a gradient to give rows in the table different colors based on their value. Low values will use colors in the lower indexes while higher values will use colors in the higher indexes.
- tableOptions: Object. Required. Customizations for the table.
  - fixFirstColumn: boolean. Optional. Defaults to true when excluded. Determines whether the first column in the table should be hidden.
  - verticalTimeAxis: boolean. Optional. Defaults to true when excluded. true sets the columns for time values to display vertically with column headings at the top in a horizontal row. false will display columns horizontally as rows, with column headings at the left in a vertical column. Warning: when using false, any time-like values may cause the entire table to display incorrectly if they are not set to visible: false in fieldOptions.
  - sortBy: Object. Optional. An object that represents a column in the table that will be sorted in ascending order upon first rendering of the table. User actions may change the sort order and/or the selected column. The object contains the following properties:
    - internalName: string. Required. Read only. The name of the column as referenced internally by Giraffe code.
    - displayName: string. Required. The name of the column to display.
    - visible: boolean. Required. Determine whether to show the column in the table or not. true has no effect, as by default all columns are shown even when not represented in fieldOptions. false will hide the column.
- fieldOptions: array[Object, ...]. Required. An array of objects that represent the columns in the table. By default all columns are shown with the internal name unless modified in this array. Each object contains the following properties:
  - internalName: string. Required. Read only. The name of the column as referenced internally by Giraffe code.
  - displayName: string. Required. The name of the column to display.
  - visible: boolean. Required. Determine whether to show the column in the table or not. true has no effect, as by default all columns are shown even when not represented in fieldOptions. false will hide the column.
- timeFormat: string. Required. A string representing the date and time format for time values. The underlying formatter is intl-dateformat which supports a subset of the ISO 8601 formats.
- decimalPlaces: Object. Required.
  - isEnforced: boolean. Optional. Defaults to false when not included. Indicates whether the number of decimal places ("digits") will be enforced. When isEnforced is falsy or omitted, digits will be locked to 2 for stat values with a decimal and 0 for stat values that are integers, and the digits option will be ignored.
  - digits: number. Optional. Defaults to 0 when not included. Maximum 10. When digits is a non-integer number, the decimal portion is ignored. Represents the number of decimal places to display in the stat value. Displayed stat value is subject to rounding.
GaugeLayerConfig: Object. Maximum one per <Plot>. Properties are:
- type: 'gauge'. Required. Specifies that this LayerConfig is a gauge layer.
- prefix: string. Optional. The text that appears before the gauge value. Use an empty string if no text is preferred.
- suffix: string. Optional. The text that appears after the gauge value. Use an empty string if no text is preferred.
- tickPrefix: string. Optional. The text that appears before each tick label. Use an empty string if no text is preferred.
- tickSuffix: string. Optional. The text that appears after each tick label. Use an empty string if no text is preferred.
- decimalPlaces: Object. Optional.
  - isEnforced: boolean. Optional. Defaults to false when not included. Indicates whether the number of decimal places ("digits") will be enforced. When isEnforced is falsy or omitted, digits will be locked to 2 for stat values with a decimal and 0 for stat values that are integers, and the digits option will be ignored.
  - digits: number. Optional. Defaults to 0 when not included. Maximum 10. When digits is a non-integer number, the decimal portion is ignored. Represents the number of decimal places to display in the stat value. Displayed stat value is subject to rounding.
- gaugeSize: number. Optional. Defaults to π and is 3.142 ≤ gaugeSize ≤ 6.283. The size of the Gauge as measured in radians. Valid Gauge sizes range from a half circle to a full circle. Any size below π is considered π and any size above 2π is considered 2π. Rounded to 3 decimal places.
- gaugeColors: array[Object, ...]. Required. An array of objects that defines the colors of the Gauge. Each object has the following properties.
  - id: string. Required. The id for this color. Should be unique within the gaugeColors array.
  - type: 'min' | 'max' | 'threshold'. Required. The type of value associated with this color. 'min' type comes first, 'max' type comes last, and 'threshold' types are in between 'min' and 'max'. gaugeColors must contain at least one 'min' type and one 'max' type for the Gauge to have color. Only the first 'min' and first 'max' in the array are recognized for each of their respective types. The color will change as a gradient if the gaugeColors array contains only 'min' and 'max'. The color will be segmented if any 'threshold' types are included in the gaugeColors array. Segmented colors on a Gauge will not display the 'max' type's color. Exception: a full circle Gauge with only 'min' and 'max' types will be segmented and include both the 'min' and 'max' colors.
  - hex: string. Required. The color hex string for this color.
  - name: string. Required. For descriptive purposes only. The name given to this color.
  - value: number. Required. The starting gauge value associated with this color.
- gaugeTheme: Object. Optional. An object controlling additional visual styling and details of the Gauge.
  - lineCount: number. Optional. Defaults to 5 when excluded. The total number of labeled gauge lines (large ticks) not counting the first.
  - smallLineCount: number. Optional. Defaults to 10 when excluded. The total number of unlabeled gauge lines (small ticks) between two labeled gauge lines excluding the starting label but including the ending label.
  - lineColor: string. Optional. Defaults to dark grey (#545667) when excluded. The color hex string for the color of the gauge lines (ticks).
  - labelColor: string. Optional. Defaults to grey (#8e91a1) when excluded. The color hex string for the color of the labels for the gauge lines.
  - labelFontSize: number. Optional. Defaults to 13 when excluded. The CanvasRenderingContext2D font size of the gauge labels.
  - lineStrokeSmall: number. Optional. Defaults to 1 when excluded. The CanvasRenderingContext2D lineWidth of the unlabeled gauge lines (small ticks).
  - lineStrokeLarge: number. Optional. Defaults to 3 when excluded. The CanvasRenderingContext2D lineWidth of the labeled gauge lines (large ticks).
  - tickSizeSmall: number. Optional. Defaults to 9 when excluded. The CanvasRenderingContext2D lineTo coordinate length of the unlabeled gauge lines (small ticks). Use a different value than tickSizeLarge to visually distinguish the length of the gauge lines (ticks).
  - tickSizeLarge: number. Optional. Defaults to 18 when excluded. The CanvasRenderingContext2D lineTo coordinate length of the labeled gauge lines (large ticks). Use a different value than tickSizeSmall to visually distinguish the length of the gauge lines (ticks).
  - minFontSize: number. Optional. Defaults to 22 when excluded. The CanvasRenderingContext2D font size of the Gauge's value. Values below a certain size will be ignored and defaulted to a size that is based on the current size of the Gauge.
  - minLineWidth: number. Optional. Defaults to 24 when excluded. The CanvasRenderingContext2D lineWidth or thickness of the Gauge's colors. Values below a certain size will be ignored an