@influxdata/giraffe

Giraffe

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

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

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>
  

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.

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

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.

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

• 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 and trailing 0 will be truncated. For example: digits is 2 and stat value is 1.299 which rounds to 1.30 and then becomes 1.3 when displayed.

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