victory-cursor-container

VictoryCursorContainer

victory-cursor-container@^30.0.0 exports VictoryCursorContainer, cursorContainerMixin and CursorHelpers

View these docs at https://formidable.com/open-source/victory/docs/victory-cursor-container to see live examples.

VictoryCursorContainer adds a cursor to a chart to inspect coordinates. The cursor can either be a 2-dimensional crosshair, or a 1-dimensional line. The cursor moves with the mouse (or on touch on mobile devices) along the visible domain of the chart. The cursor can also display a label for the active coordinates using the cursorLabel prop.

VictoryCursorContainer may be used with any Victory component that works with an x-y coordinate system, and should be added as the containerComponent of the top-level component. However, the component that uses it must be standalone (standalone={true}), which is the default for all top-level Victory components.

Note that the cursor allows you to inspect the entire domain, not just the data points. If you would like to instead highlight only the data points, consider using VictoryVoronoiContainer.

<VictoryScatter
  containerComponent={
    <VictoryCursorContainer
      cursorLabel={(d) => `${round(d.x, 2)}, ${round(d.y, 2)}`}
    />
  }
/>

Props

VictoryCursorContainer uses a superset of props used by VictoryContainer. All props are optional.

cursorComponent

type: element

The cursorComponent prop takes a component instance which will be used to render a cursor element. The new element created will be supplied with x1, y1, x2 and y2 positioning props. If a cursorComponent is not supplied, a new Line component will be rendered.

In order to customize, add styling to a LineSegment supplied to the cursorComponent prop.

<VictoryScatter
  containerComponent={
    <VictoryCursorContainer
      cursorComponent={<LineSegment style={{ strokeDasharray: '2,4' }} />}
      cursorLabel={(d) => `${round(d.x, 2)}, ${round(d.y, 2)}`}
    />
  }
/>

default: cursorComponent={<Line/>}

cursorDimension

type: "x" || "y"

When the cursorDimension prop is set, the cursor will be a line to inspect the given dimension (either "x" or "y"). When this prop is not specified, the cursor will be a 2-dimensional crosshair. For example, if you would like to inspect the time of time-series data, set dimension={"x"}; the cursor will then be a vertical line that will inspect the time value of the current mouse position.

example: cursorDimension="x"

<VictoryScatter
  containerComponent={
    <VictoryCursorContainer
      cursorDimension="x"
      cursorLabel={(d) => `${round(d.x, 2)}, ${round(d.y, 2)}`}
    />
  }
/>

cursorLabel

type: function

The cursorLabel prop defines the label that will appear next to the cursor. A label will only appear if cursorLabel is set. This prop should be given as a function of a point (an Object with x and y properties).

example: cursorLabel={(point) => point.x}

cursorLabelComponent

type: element

The cursorLabelComponent prop takes a component instance which will be used to render a label for the cursor. The new element created from the passed cursorLabelComponent will be supplied with the following props: x, y, active, text. If cursorLabelComponent is omitted, a new VictoryLabel will be created with the props described above.

default: cursorLabelComponent={<VictoryLabel/>}

cursorLabelOffset

type: number || { x: number, y: number }

The cursorLabelOffset prop determines the pixel offset of the cursor label from the cursor point. This prop should be an Object with x and y properties, or a number to be used for both dimensions.

default: cursorLabelOffset={{ x: 5, y: -10 }}

defaultCursorValue

type: number || { x: number, y: number }

Whenever the mouse is not over the chart, the cursor will not be displayed. If instead you would like to keep it displayed, use the defaultCursorValue prop to set the default value. The prop should be a point (an Object with x and y properties) for 2-dimensional cursors, or a number for 1-dimensional cursors.

examples: defaultCursorValue={{x: 1, y: 1}}, defaultCursorValue={0}

disable

type: boolean

When the disable prop is set to true, VictoryCursorContainer events will not fire.

onCursorChange

type: function

If provided, the onChange function will be called every time the cursor value changes. onCursorChange is called with value (the updated cursor value) and props (the props used by VictoryCursorContainer). A common use for onChange is to save the cursor value to state and use it in another part of the view.

example: onChange={(value, props) => this.setState({cursorValue: value})}

Changelog

32.0.0 (2019-02-27)

Horizontal Chart Improvements!

#1258

The goal of this change is to make it possible to turn any existing chart into a horizontal chart by adding the horizontal prop to the chart without needing to alter any other props.

• supports horizontal versions of all chart types without needing to alter data
• supports all event containers for horizontal charts
• enforces consistency across props that take x and y values so that the x value always refers to the independent dimension, and the y value always refers to the dependent dimension.
• the orientation of VictoryAxis components is no longer tied to whether or not they are the dependentAxis

Breaking Changes

Most Horizontal Charts The change in how props with x and y values are treated (i.e. scale, domain, etc) will be a breaking change for most horizontal charts. In most cases, reversing the x and y values of props you are providing to your horizontal chart will be sufficient to correct the change. For example:

<VictoryChart horizontal scale={{ x: "log" }} domain={{ y: [4, 9] }}>
  <VictoryBar
    data={[
      { x: 5, y: 0.1 },
      { x: 6, y: 1 },
      { x: 7, y: 10 },
      { x: 8, y: 100 }
    ]}
  />
</VictoryChart>

Should be changed to:

<VictoryChart horizontal scale={{ y: "log" }} domain={{ x: [4, 9] }}>
  <VictoryBar
    data={[
      { x: 5, y: 0.1 },
      { x: 6, y: 1 },
      { x: 7, y: 10 },
      { x: 8, y: 100 }
    ]}
  />
</VictoryChart>

Props affected by this change are: scale, domain, maxDomain, minDomain, domainPadding, and categories

Horizontal Charts with Event Containers Dimension props such as brushDimension have changed so that they always refer to the dimension of the target variable (x for the independent variable, and y for the dependent variable). For example, a VictoryBrushContainer component with brushDimension="x" will move and expand only in the independent dimension regardless of whether the chart is horizontal.

Props affected by this change are: brushDimension, cursorDimension, selectionDimension, voronoiDimension, and zoomDimension

Horizontal Charts with Custom dataComponents The position values (i.e. x, y, x0, y0) supplied to custom dataComponents from components like VictoryChart will be scaled for the layout of the horizontal chart. Users who rely on these values may need to flip them or adjust them depending on their use case

Horizontal VictoryBoxPlot Previously VictoryBoxPlot required data to be flipped (x values flipped with y values) in order to plot horizontal charts. This is no longer required, and providing data in this format will no longer work correctly. To correct for this change, it should be sufficient to flip the data used in horizontal charts