@influxdata/giraffe

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

1. In your React code, import the Plot component and the newTable utility function

  import {Plot, newTable} from '@influxdata/giraffe'
  

1. Build the config object. a. Required properties:

   • table is data built using the newTable utilty function or built from Flux results, see Flux example
   • layers is an array of objects that describe how to render the data.

   b. Optional properties include customizations for

   • gridlines: color and opacity
   • cursor: type of mouse cursor
   • axes: appearance, color, opacity, and scaling
   • ticks: generation, formatting and labeling, font, and color
   • legend (tooltip): labeling and styling

   For details on all configuration properties, skip to config documentation.

   Here is an example of building the config object while skipping optional properties:

  // Example table and layer

  const table = newTable(5)
    .addColumn('_time', 'time', [1589838401244, 1589838461244, 1589838521244, 1589838581244, 1589838641244])
    .addColumn('_value', 'number', [2.58, 7.11, 4.79, 8.89, 2.23])

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

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

1. Render your component by passing the config object as the config prop to the <Plot> component. Be sure that the parent component around <Plot> has both a height and a width measured in positive values. If either is not a positive value, the graph will not be visible.

   For example, to make a <Plot> that adjusts to screen height and width, in your React rendering code return this element:

  // return this element in your React rendering code:

  <div
    style={{
      width: "calc(70vw - 20px)",
      height: "calc(70vh - 20px)",
      margin: "40px",
    }}
  >
    <Plot config={config} />
  </div>
  

Example Using Flux

Two ways:

I. When generating the table through a Flux result:

• call the fromFlux utility function on the csv that is 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:

  import {Plot, fromFlux} from '@influxdata/giraffe'

  // ...

  const fluxResultCSV = `#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string
#group,false,false,true,true,false,false,true,true,true,true
#default,_result,,,,,,,,,
,result,table,_start,_stop,_time,_value,_field,_measurement,example,location
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:31:33.95Z,29.9,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:55:23.863Z,28.7,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:50:52.357Z,15,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:37.198Z,24.8,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:53.033Z,23,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T20:19:21.88Z,20.1,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-10T22:20:40.776Z,28.7,value,temperature,index.html,browser
`

  const dataFromFlux = fromFlux(fluxResultCSV)

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

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

  // ...

  // return this element in your React rendering code:

  <div
    style={{
      width: "calc(70vw - 20px)",
      height: "calc(70vh - 20px)",
      margin: "40px",
    }}
  >
    <Plot config={config} />
  </div>
  

II. When using the comma separate values (CSV) from the Flux query as the fluxResponse property:

  import {Plot} from '@influxdata/giraffe'

  // ...

  const fluxResponse = `#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string
#group,false,false,true,true,false,false,true,true,true,true
#default,_result,,,,,,,,,
,result,table,_start,_stop,_time,_value,_field,_measurement,example,location
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:31:33.95Z,29.9,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:55:23.863Z,28.7,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:50:52.357Z,15,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:37.198Z,24.8,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:53.033Z,23,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T20:19:21.88Z,20.1,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-10T22:20:40.776Z,28.7,value,temperature,index.html,browser
`

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

  const config = {
    fluxResponse,
    layers: [lineLayer],
  }

  // ...

  // return this element in your React rendering code:

  <div
    style={{
      width: "calc(70vw - 20px)",
      height: "calc(70vh - 20px)",
      margin: "40px",
    }}
  >
    <Plot config={config} />
  </div>
  

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 (tooltip) customization

  const config = {
    property: value,
    ...
  }

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 excluded, Giraffe attempts to use as many ticks as possible on the x-axis while keeping reasonable spacing between them.

• 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 excluded, Giraffe attempts to use as many ticks as possible on the y-axis while keeping reasonable spacing between them.

• 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:

  const config = {
    // ...
  
    valueFormatters: {
      _time: (t) => new Date(t).toLocaleTimeString(),  // ECMAScript time to human-readable time stamp
      _value: (num) => num.toFixed(2),                 // values fixed to 2 decimal places
    },
  
    // ...
  }
  

• 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

• table: Object. Optional. When missing, config will look for fluxResponse to create the table. When both are missing, config will create an empty table. 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.

• fluxResponse: String. Optional. Ignored when table is present; table takes precendence. When both are missing, config will create an empty table. A string of comma separated values returned from a Flux query representing the data to be visualized.

• 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. The x 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 x domain to set the minimum and maximum value of the x-axis. Any brush interaction with the <Plot> that should change the x domain will call the onSetXDomain option when the component is in controlled mode. Double clicking the plot will call onResetXDomain. If the xDomain option is not passed, then the component is "uncontrolled". It will compute, set, and reset the xDomain automatically.

• onSetXDomain: function(array[min, max]). Optional. See above regarding xDomain.

• onResetXDomain: function(). Optional. See above regarding xDomain.

• yDomain: array[min, max]. Optional. 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 call the onSetYDomain option when the component is in controlled mode. Double clicking the plot will call onResetYDomain. If the yDomain option is not passed, then the component is "uncontrolled". It will compute, set, and reset the yDomain automatically.

• onSetYDomain: function(array[min, max]). Optional. See above regarding yDomain.

• onResetYDomain: function(). Optional. See above regarding yDomain.

Legend Tooltip properties

• legendFont: string. Optional. The CSS font value for the styling of the legend (tooltip).

• legendFontColor: string. Optional. The CSS color value of the column headers in the legend (tooltip). The rest of the legend will use the color scheme set by the LayerConfig's colors options.

• legendFontBrightColor: string. Optional. Recommendation: do not include. The CSS color value of any text that is not a column header or in a row inside the legend (tooltip). Currently no such text exists and may be added in the future.

• legendBackgroundColor: string. Optional. The CSS color value of the background in the legend (tooltip).

• legendBorder: string. Optional. The CSS border value for the styling of the border around the legend (tooltip).

• 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.

• legendColumns: array[string, ...]. Optional. When included, this array will determine which column key names that should be included in the legend (tooltip). If this option is included as an empty array, the legend will be empty.

• legendOpacity: number. Optional. Defaults to 1.0 when excluded. The CSS opacity of the entire <Tooltip> element (or legend). 0 means the legend is invisible, while 1.0 means the legend covers anything underneath.

• 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.

Utility Functions

Giraffe comes with utility functions.

• fromFlux: function(string). Takes a Flux CSV, converts it, and returns a 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.

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 key name of the column that should be visualized on the x-axis.

  • y: string. Required. The column key name of the column that should be visualized on the y-axis.

  • fill: array[string, ...]. Optional. An array of column key 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". Optional. Defaults to "x" when not included. Indicates whether the legend (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

  • maxTooltipRows: number. Optional. Defaults to 24 when not included. The maximum number of data rows to display in the legend (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 key name of the column that should be visualized on the x-axis.

  • y: string. Required. The column key name of the column that should be visualized on the y-axis.

  • fill: array[string, ...]. Optional. An array of column key 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.

  • hoverDimension: "x" | "y" | "xy". Optional. Defaults to "x" when not included. Indicates whether the legend (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

  • maxTooltipRows: number. Optional. Defaults to 24 when not included. The maximum number of data rows to display in the legend (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 key name of the column that should be visualized on the x-axis.

  • y: string. Required. The column key name of the column that should be visualized on the y-axis.

  • fill: array[string, ...]. Optional. An array of column key 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.

• 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 key 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 key 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.

  • 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.

  • strokePadding: number. Optional. The space around all four sides of each fill column or bin. The amount of spacing is the width and height used in the CanvasRenderingContext2D rect function.

• 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 key name of the column that should be visualized on the x-axis.

  • y: string. Required. The column key 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:

  <HoverTimeProvider>
    <div
      style={{
        width: "calc(70vw - 20px)",
        height: "calc(70vh - 20px)",
        margin: "40px",
      }}
    >
      <Plot config={config} />
    </div>
  </HoverTimeProvider>
  

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. Required. The text that appears before the gauge value. Use an empty string if no text is preferred.

  • suffix: string. Required. The text that appears after the gauge value. Use an empty string if no text is preferred.

  • tickPrefix: string. Required. The text that appears before each tick label. Use an empty string if no text is preferred.

  • tickSuffix: string. Required. The text that appears after each tick label. Use an empty string if no text is preferred.

  • 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.

  • gaugeSize: number. Optional. 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. 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.

  • theme: Object. Optional. An object controlling additional visual styling and details of the Gauge.

    • lineCount: number. Optional. The total number of labeled gauge lines (large ticks) not counting the first.

    • smallLineCount: number. Optional. 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. The color hex string for the color of the gauge lines (ticks).

    • labelColor: string. Optional. The color hex string for the color of the labels for the gauge lines.

    • labelFontSize: number. Optional. The CanvasRenderingContext2D font size of the gauge labels.

    • lineStrokeSmall: number. Optional. The CanvasRenderingContext2D lineWidth of the unlabeled gauge lines (small ticks).

    • lineStrokeLarge: number. Optional. The CanvasRenderingContext2D lineWidth of the labeled gauge lines (large ticks).

    • tickSizeSmall: number. Optional. 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. 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. 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. The CanvasRenderingContext2D lineWidth or thickness of the Gauge's colors. Values below a certain size will be ignored and defaulted to a size that is based on the current size of the Gauge.

    • valueColor: string. Optional. The color hex string for the color of the Gauge's current value.

    • valuePositionXOffset: number. Optional. The CanvasRenderingContext2D fillText coordinate offset for the horizontal dimension that the Gauge's value should be moved from its default position.

    • valuePositionYOffset: number. Optional. The CanvasRenderingContext2D fillText coordinate offset for the vertical dimension that the Gauge's value should be moved from its default position.

    • needleColor0: string. Optional. The color hex string of the starting color for the color gradient of the Gauge's needle. needleColor0 should be used in conjunction with needleColor1.

    • needleColor1: string. Optional. The color hex string of the ending color for the color gradient of the Gauge's needle. needleColor1 should be used in conjunction with needleColor0.

    • overflowDelta: number. Optional. This constant expresses how far past the gauge min or gauge max the needle should be drawn if the value for the needle is less than gauge min or greater than the gauge max. It is expressed as a percentage of the circumference of a circle, e.g. 0.5 means draw halfway around the gauge from the min or max value.

• SingleStatLayerConfig: Object. No limit but generally one per <Plot>. Using more than one requires additional styling through configuration and is not recommended.

  
  A Single Stat layer is a pre-defined custom layer that displays a single value on top of any other plot type, or by itself, but usually displayed on top of (single) line graphs. The displayed value is the latest value by timestamp. If more than one value has the latest timestamp, then the first value in the table with the latest timestamp will be displayed. Currently, there is no guarantee which value will be considered the first value when there are multiple values with the same timestamp.

  • type: 'single stat'. Required. Specifies that this LayerConfig is a single stat layer.

  • prefix: string. Required. The text that appears before the stat value. Use an empty string if no text is preferred.

  • suffix: string. Required. The text that appears after the stat value. Use an empty string if no text is preferred.

  • 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.

  • textColor: string. Required. The CSS color value of the entire Single Stat to display including prefix, the stat value, and suffix.

  • textOpacity: number. Optional. Defaults to 1 when not included. A value between 0 and 1 inclusive, specifying the opacity of the entire text for the Single Stat including prefix, the stat value, and suffix. 0 is fully transparent (invisible) while 1 is fully opaque.

  • backgroundColor: string. Optional. Recommendation: do not include. Defaults to transparent when not included. The CSS background color of the background, which covers the area surrounded by the axes and border (whether displayed or not) of the <Plot>.

  • testID: string. Optional. A string value for the data-testid prop on the element for the Single Stat. Primarily used for automated testing.

    
    The following optional properties affect element attributes in the DOM tree of the Single Stat. Its structure looks like this

      <div class="giraffe-layer giraffe-layer-single-stat">
        <div class="giraffe-single-stat--resizer">
          <svg class="giraffe-single-stat--svg">
            <text class="giraffe-single-stat--text"></text>
          </svg>
        </div>
      </div>
    

  • style: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for inline styling .giraffe-layer-single-stat by setting its style property. If used, please be aware of existing default styles that may need to be overridden. backgroundColor cannot be overridden and is controlled by the backgroundColor option (see above). See the SINGLE_STAT_DEFAULT_STYLE here.

  • resizerStyle: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for inline styling .giraffe-single-stat--resizer by setting its style property. If used, please be aware of existing default styles that may need to be overridden. See the SINGLE_STAT_RESIZER_DEFAULT_STYLE here.

  • svgAttributes: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for the element attributes of .giraffe-single-stat--svg. If used please be aware of the existing default attributes that may need to be overridden. See the SINGLE_STAT_SVG_DEFAULT_ATTRIBUTES here.

  • svgStyle: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for inline styling .giraffe-single-stat--svg by setting its style property. This element has no existing default styling.

  • svgTextAttributes: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for the element attributes of .giraffe-single-stat--text. If used please be aware of the existing default attributes that may need to be overridden. opacity cannot be overridden and is controlled by the textOpacity option (see above). See the SINGLE_STAT_SVG_TEXT_DEFAULT_ATTRIBUTES here.

  • svgTextStyle: Object. Optional. Recommendation: do not include. An object containing the key-value pairs used for inline styling .giraffe-single-stat--text by setting its style property. If used, please be aware of existing default styles that may need to be overridden. fill cannot be overridden and is controlled by the textColor option (see above). See the SINGLE_STAT_SVG_TEXT_DEFAULT_STYLE here.

• CustomLayerConfig: Object. No limit per <Plot>.

  A custom layer is an overlay on the Plot that is not one of the above pre-defined plot types. A render callback function is passed in as the renderer for the custom layer. It has two properties:

  • type: 'custom'. Required. Specifies that this LayerConfig is a custom layer.

  • render: function(Object). Required. A configuration-defined callback function called with a CustomLayerRenderProps and returns a JSX Element. The CustomerLayerRenderProps Object has the following properties available to use in the callback function:

    • key: string | number. As part of a React list of rendered elements, a unique key prop is required on the JSX Element returned by the custom layer's render function. Use this key for the key prop in the JSX Element.

    • xScale: function(number). The scaling function produced by the config's xScale property. Can be used for scaling the JSX Element's x-dimension.

    • yScale: function(number). The scaling function produced by the config's yScale property. Can be used for scaling the JSX Element's y-dimension.

    • xDomain: array[min, max]. See the config's xDomain property. Gives the JSX Element access to the <Plot>'s xDomain.

    • yDomain: array[min, max]. See the config's yDomain property. Gives the JSX Element access to the <Plot>'s yDomain.

    • width: number. See the config's width property. Gives the JSX Element access to the <Plot>'s width.

    • innerWidth: number. The width (see above) without the size of the area to the left of the y-axis.

    • height: number. See the config's width property. Gives the JSX Element access to the <Plot>'s height.

    • innerHeight: number. The height (see above) without the size of the area below the x-axis.

    • columnFormatter: function(string). A function that takes a column key and returns a function that can format values for that type of column. When columnFormatter is called with "_time", it returns a function that takes ECMAScript time values and returns the human-readable time stamp for that value.