Skip to content

XYFrame

Jump to bottom Edit New page
Shelby Sturgis edited this page Aug 14, 2017 · 69 revisions

A <Frame> that displays continuous data along the x and y axis. Examples include time series charts, scatterplots, line, and area charts. <XYFrame> charts render points, lines, and/or area elements. Rendering and styling is based on each element's corresponding properties.

import { XYFrame } from 'semiotic'

<XYFrame
   points={[{price: 1.25, size: 15}, {price: 2.25, size: 12}, ...]}
   pointStyle={{ fill: "blue" }}
   xAccessor={"price"}
   yAccessor={"size"}
/>

<API Reference>

General Properties

size: { [width, height] }

If size is specified, sets the width and height of the frame from the array of values. The array must contain two numbers which represents the width and height, respectively.

Note: Margin will not be added to the frame size. It's more like CSS padding.

<XYFrame size={ [500,500] } ... />

xAccessor: { string | function }

If xAccessor is specified, determines how x values are accessed from the data array. In the case the data consists of an array of objects, a string can be used to assess the x value(s). A function can also be used to access the x value(s).

<!-- String option -->
<!-- e.g. data=[{x: 1, y: 2}, {x:2, y: 4}, ... ] -->
<XYFrame xAccessor={ "x" } ... />

<!-- Function option -->
<!-- e.g. data=[[1, 2], [2, 4], ... ] -->
<XYFrame xAccessor={ d => d[0] } ... />

yAccessor: { string | function }

If yAccessor is specified, determines how y values are accessed from the data array. In the case the data consists of an array of objects, a string can be used to assess the y value(s). A function can also be used to access the y value(s).

<!-- String option -->
<!-- e.g. data=[{x: 1, y: 2}, {x: 2, y: 4}, ... ] -->
<XYFrame yAccessor={ "y" } ... />

<!-- Function option -->
<!-- e.g. data=[[1, 2], [2, 4], ... ] -->
<XYFrame yAccessor={ d => d[1] } ... />

title: { string | JSX }

If title is specified, sets the text for the chart title, which appears centered at the top of the chart. The title can be either a string or JSX object.

<!-- String option -->
<XYFrame title={ "Chart Title" } ... />

<!-- JSX option -->

margin: { number | object }

If margin is specified, sets the margin(s) on the frame. The margin can be set to one number, which is applied equally to all sides, or as an object.

<!-- Single number option -->
<XYFrame margin={ 10 } ... />

<!-- Object option -->
<XYFrame margin={ { top: 5, bottom: 10, left: 15, right: 20 } } ... />

xScaleType: { d3-scale }

Custom D3 scale for the x axis. Defaults to scaleLinear().

<XYFrame xScaleType={ d3.scaleTime() } ... />

yScaleType: { d3-scale }

Custom D3 scale for the y axis. Defaults to scaleLinear().

<XYFrame yScaleType={ d3.scaleLinear() } ... />

xExtent: { [min, max] }

If xExtent is specified, sets the min and/or max value(s) for the x axis. The array may contain two numbers, or it can contain a number and an undefined value, if you only want to set the min or max extent.

<!-- min and max values set -->
<XYFrame xExtent={ [20,250] } ... />

<!-- only min value set -->
<XYFrame xExtent={ [20, undefined] } ... />

yExtent: { [min, max] }

If yExtent is specified, sets the min and/or max value(s) for the y axis. The array may contain two numbers, or it can contain a number and an undefined value, if you only want to set the min or max extent.

<!-- min and max values set -->
<XYFrame yExtent={ [0,500] } ... />

<!-- only max value set -->
<XYFrame yExtent={ [undefined, 350] } ... />

invertX: { boolean }

If invertX is specified, inverts the x axis such that the min and max values are transposed.

<XYFrame invertX={ true } ... />

invertY: { boolean }

If invertY is specified, inverts the y axis such that the min and max values are transposed.

<XYFrame invertY={ true } ... />

showLinePoints: { boolean }

If showLinePoints is specified, displays the points that make up the line and/or area elements.

<XYFrame showLinePoints={ true } ... />

Point Rendering

points: { [data] }

An array of arrays or objects representing individual points on a chart. If you want to show points on a line or area chart, use the showLinePoints property.

var points = [[1,2], [3,4], [5,8], [7,16], [9,32], [11,64], [13,128]];

function MyScatterPlot() {
  return <XYFrame 
           xAccessor={ d => d[0] } 
           yAccessor={ d => d[1] }
           points={ points } />;
}

pointStyle: { object | function }

If pointStyle is specified, sets the inline css style of each point element.

<!-- Object option -->
<XYFrame pointStyle={ { fill: "red", stroke: "grey", strokeWidth: 1 } } ... />

<!-- Function option -->
<XYFrame
  ... 
  pointStyle={ d => ({ fill: d.fill, stroke: d.stroke, strokeWidth: d.strWidth }) } 
/>

pointClass: { string | function }

If pointClass is specified, sets the css class of each point element.

<!-- String option -->
<XYFrame pointClass={ "scatter-points" } ... />

<!-- Function option -->
<XYFrame pointClass={ d => d.className } ... />

canvasPoints: { boolean | function }

If canvasPoints is specified, determines whether or not to render points to Canvas instead of SVG. The canvasPoints attribute accepts a boolean or a function that evaluates each point and returns a boolean.

<!-- Boolean option -->
<XYFrame canvasPoints={ true } ... />

<!-- Function option -->
<XYFrame canvasPoints={ d => d.radius === 5 } ... />

customPointMark: { JSX | function }

If customPointMark is specified, renders a JSX <Mark> for each point, otherwise points use <Mark markType="circle" />. The customPointMark attribute accepts a JSX object or function that returns a JSX object as the marker for each point.

Note: The value(s) of the pointStyle attribute is then applied to the custom mark, but only at the top level. So if you want to make multipart graphical objects, have the customPointMark declare the style.

<!-- JSX option -->
<XYFrame customPointMark={ <Mark markType="rect" /> } ... />

<!-- Function option -->
<XYFrame customPointMark={ d => (<Mark markType="rect" />) } ... />

Line Rendering

lines: { [data] }

An array of arrays or objects representing individual points along a line. If you want to show points along the line, use the showLinePoints property.

var lines = [[1,2], [3,4], [5,8], [7,16], [9,32], [11,64], [13,128]];

function MyLineChart() {
  return <XYFrame 
           xAccessor={ d => d[0] } 
           yAccessor={ d => d[1] }
           points={ lines } />;
}

lineDataAccessor: { string | function }

If lineDataAccessor is specified, determines how line coordinates are accessed from the data array passed to the lines attribute. Defaults to coordinates.

<!-- String option -->
<XYFrame lineDataAccessor={ "lineValues" } ... />

<!-- Function option -->
<XYFrame lineDataAccessor={ d => d.lineValues } ... />

customLineType: { string | object }

If customLineType is specified, renders one of the supported line types. The attribute accepts a string corresponding to one of the supported line types or an object with a type key and string value corresponding to one of the supported line types. An optional options key on the object that determines how the lines are generated is also supported.

<!-- String option -->
<XYFrame customLineType={ "dividedLine" } ... />

<!-- Object option -->
<XYFrame customLineType={ { type: "dividedLine", options: {} } } ... />

lineStyle: { object | function }

If lineStyle is specified, sets the inline css style of each line element.

<!-- Object option -->
<XYFrame lineStyle={ { stroke: "#e3e3e3", strokeWidth: 2 } } ... />

<!-- Function option -->
<XYFrame
  ... 
  lineStyle={ d => ({ stroke: d.stroke, strokeWidth: d.strWidth }) } 
/>

lineClass: { string | function }

If lineClass is specified, sets the css class of each line element.

<!-- String option -->
<XYFrame lineClass={ "line" } ... />

<!-- Function option -->
<XYFrame lineClass={ d => d.className } ... />

lineIDAccessor: { string | function }

If lineIDAccessor is specified, sets the id attribute of the corresponding line. The lineIDAccessor accepts a string or a function that returns a string indicating the id name. Defaults to "id".

<!-- String option -->
<XYFrame lineIDAccessor={ "myLineId" } ... />

<!-- Function option -->
<XYFrame lineIDAccessor={ d => d.id } ... />

customLineMark: { function }

Is customLineMark is specified, renders a custom JSX element for each line. For example, <DividedLines> can be used in replace of normal lines or other line generators taking advantage of the <Frame>'s settings. The customLineMark attribute accepts a function that returns a JSX object

<XYFrame customLineMark={ d => (<DividedLines ... />) } ... />

canvasLines: { boolean | function }

If canvasLines is specified, renders line elements in Canvas. The canvasLines attribute accepts a boolean or a function that evaluates a line and returns a boolean that determines whether or not to render the line to Canvas instead of SVG.

<!-- Boolean option -->
<XYFrame canvasLines={ true } ... />

<!-- Function option -->
<XYFrame canvasLines={ (d, i) => } ... />

defined: { function }

If defined is specified, sets the accessor function that controls where the line is defined. Similar to D3's line.defined API.

<XYFrame defined={ d => !isNaN(d[1]) } ... />

Area Rendering

areas: { [] }

An array of arrays or objects representing individual points on a chart. If you want to show points on an area chart, use the showLinePoints property.

var points = [[1,2], [3,4], [5,8], [7,16], [9,32], [11,64], [13,128]];

function MyAreaChart() {
  return <XYFrame 
           xAccessor={ d => d[0] } 
           yAccessor={ d => d[1] }
           areas={ points } />;
}

areaDataAccessor: { string | function }

If areaDataAccessor is specified, determines how area coordinates are accessed from the data array passed to the areas attribute. Defaults to coordinates.

<!-- String option -->
<XYFrame areaDataAccessor={ "areaValues" } ... />

<!-- Function option -->
<XYFrame areaDataAccessor={ d => d.areaValues } ... />

areaStyle: { function | object }

If areaStyle is specified, sets the inline css style of each area element.

<!-- Object option -->
<XYFrame areaStyle={ { fill: "#e3e3e3", stroke: "#e3e3e3" } } ... />

<!-- Function option -->
<XYFrame
  ... 
  areaStyle={ d => ({ fill: d.fill, stroke: d.stroke }) } 
/>

areaClass: { string | function }

If areaClass is specified, sets the css class of each area element.

<!-- String option -->
<XYFrame areaClass={ "area" } ... />

<!-- Function option -->
<XYFrame areaClass={ d => d.className } ... />

canvasAreas: { boolean | function }

If canvasAreas is specified, renders area elements in Canvas. The canvasAreas attribute accepts a boolean or a function that evaluates an area and returns a boolean that determines whether or not to render the area to Canvas instead of SVG.

<!-- Boolean option -->
<XYFrame canvasAreas={ true } ... />

<!-- Function option -->
<XYFrame canvasAreas={ (d, i) => } ... />

Annotation and Decoration

tooltipContent: function

A function returning JSX HTML to display in the tooltip (only active if hoverAnnotation is set to true). The tooltip is passed the data point (which if part of a line or area will be decorated with a corresponding parentLine or parentArea pointer to that object). The content is placed on and directly above the hovered point, so take that into account when using CSS to style the position and any additional elements. You can drop any HTML into this floating div, including another frame, if you want to have data visualization in your data visualization so you can visualize while you visualize.

axes: array

An array of objects that defines axes. These objects roughly correspond to the options in D3 array, with extended options such as label.

legend: bool or object

A boolean or object determining whether to turn on a legend. Currently only works with line data. If set to true, will place a legend on the upper right corner of the chart area. Legends are 100px wide, so you can account for this in your right-hand margin. Can also take an object with { position } that can be set to "right" to get the default behavior or "left" to place it on the top left corner or an array of exact XY position for the legend. The legend will automatically have items for each line, labeled with the string value that corresponds to the lineIDAccessor of the line.

annotations: array

An array of objects to be processed using the frame's built-in annotation rules or the custom defined rules.

svgAnnotationRules: function

A function that takes an annotation object and returns a JSX SVG element. The function is sent { d, i, screenCoordinates, xScale, yScale, xAccessor, yAccessor, xyFrameProps, xyFrameState, areas, points, lines }

htmlAnnotationRules: function

A function that takes an annotation object and returns a JSX HTML element. The function is sent { d, i, screenCoordinates, xScale, yScale, xAccessor, yAccessor, xyFrameProps, xyFrameState, areas, points, lines }. Elements can be placed using CSS left and top and will overlay on the chart. Internally, the default annotation for tooltips uses this method.

annotationSettings: { object }

An object with { layout, pointSizeFunction, labelSizeFunction } containing custom annotation settings to enable annotations bumping out of each others' way or placing them in the margins.

matte: bool or object

Whether to turn on a matte (a border that covers the margin area to hide overflow) or a JSX custom matte.

backgroundGraphics: array or JSX

A JSX or array of JSX to display behind the chart.

foregroundGraphics: array or JSX

A JSX or array of JSX to display in front of the chart.

Interaction

hoverAnnotation: bool

Turn on automatic tooltips with a voronoi overlay to improve interaction. Content of the tooltips defaults to the x and y value and can be customized with tooltipContent

customHoverBehavior: function

A function to fire on hover that passes the data being hovered over.

customClickBehavior: function

A function to fire on click that passes the data being hovered over.

customDoubleclickBehavior: function

A function to fire on doubleclick that passes the data being hovered over.

interaction: object

An object passed to the interaction layer that is currently only used to determine whether to activate the XY brush, its settings, and the actions to fire on its start, brush and end events. Used under the hood in MinimapXYFrame to enable the functionality in the minimap.

Miscellaneous

dataVersion: string

A simple optimization option. If you set dataVersion (a string) then XYFrame will not update the visualization layer until it receives a different string. This allows you to manage rendering when your code is making React re-render your chart all the time.

name: string

Used internally to identify frames, which comes in handy when you need to link frames together.

position: array

Just an offset and hardly ever useful

additionalDefs: array or JSX

A JSX or array of JSX to be injected into the visualization layer's SVG defs.

download: bool

Enable a download button to download the data as a CSV

downloadFields: array

The field keys to download from each datapoint. By default, the CSV download only shows the x and y values.

Add a custom footer
Add a custom sidebar
Clone this wiki locally