Victory
Victory

About Docs Gallery Support GitHub FAQs

#
Common Props

Not every component uses all of these props. These are all common to things like `VictoryBar`, `VictoryScatter`, but other components like `VictoryStack` use only some of them.

The props explanations given here are general. Each component docs page should be considered as the the source of truth for a component's props, and any caveats will be listed there.

##
animate

`type: boolean || object`

The `animate` prop specifies props for VictoryAnimation and VictoryTransition to use. The animate prop may be used to specify the duration, delay, and easing of an animation as well as the behavior of `onEnter` and `onExit` and `onLoad` transitions. Each Victory component defines its own default transitions, be these may be modified, or overwritten with the `animate` prop. An `animationWhitelist` may also be specified on the `animate` prop. When given, only props specified in the whitelist will animate.

See the Animations Guide for more detail on animations and transitions

example: `animate={{ duration: 2000 }}`

##
categories

`type: array[string] || { x: array[string], y: array[string] }`

The `categories` prop specifies how categorical data for a chart should be ordered. This prop should be given as an array of string values, or an object with these arrays of values specified for x and y. If this prop is not set, categorical data will be plotted in the order it was given in the data array.

note: The `x` value supplied to the `categories` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

example: `categories={{ x: ["apples", "oranges", "bananas"] }}`

##
containerComponent

`type: element`

The `containerComponent` prop takes a component instance which will be used to create a container element for standalone charts. If a `containerComponent` is not provided, the default `VictoryContainer` component will be used. Other Victory container components include:

- VictoryBrushContainer
- VictoryCursorContainer
- VictorySelectionContainer
- VictoryVoronoiContainer
- VictoryZoomContainer
- hybrid containers may be created using the createContainer helper

Victory container components all support `title` and `desc` props, which are intended to add accessibility to Victory components. The more descriptive these props are, the more accessible your data will be for people using screen readers. These props may be set by passing them directly to the supplied component. By default, all Victory container components render responsive `svg` elements using the `viewBox` attribute. To render a static container, set `responsive={false}` directly on the container instance supplied via the `containerComponent` prop. All Victory container components also render a `Portal` element that may be used in conjunction with VictoryPortal to force components to render above other children.

Container components are supplied with the following props:

- `domain`
- `height`
- `horizontal`
- `origin` (for polar charts)
- `padding`
- `polar`
- `scale`
- `standalone`
- `style`
- `theme`
- `width`

default: `containerComponent={<VictoryContainer/>}`

##
data

`type: array[object]`

Specify data via the `data` prop. By default, Victory components expect data as an array of objects with `x` and `y` properties. Use the x and y data accessor props to define a custom data format. The `data` prop must be given as an array. Data objects may also include information about styles, labels, and props that may be applied to individual data components.

Note: All values stored on the data object will be interpolated during animation. Do not store functions on data objects.

Note: As of `victory@0.26.0` styles provided via the `data` prop are no longer automatically applied. To use styles from the data object, add functional styles as in the example below.

##
dataComponent

`type: element`

The `dataComponent` prop takes a component instance which will be responsible for rendering a data element. The new element created from the passed `dataComponent` will be provided with all the props it needs to render. These props will always include `data`, `events`, `scale` and `style`. Individual components will supply additional props expected by their default `dataComponents`. See individual api docs for complete props lists. Any of these props may be overridden by passing in props to the supplied component, or modified or ignored within the custom component itself. If a `dataComponent` is not provided, each component will use its own default `dataComponent`.

See the Custom Components Guide for more detail on creating your own `dataComponents`

examples: `dataComponent={<Area/>}`

##
domain

`type: array[low, high] || { x: [low, high], y: [low, high] }`

The `domain` prop describes the range of data the component will include. This prop can be given as a array of the minimum and maximum expected values of the data or as an object that specifies separate arrays for x and y. If this prop is not provided, a domain will be calculated from data, or other available information.

note: The `x` value supplied to the `domain` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

examples:

- `domain={[-1, 1]}`
- `domain={{x: [0, 100], y: [0, 1]}}`

##
domainPadding

`type: number || array[left, right] || { x: [left, right], y: [bottom, top] }`

The `domainPadding` prop specifies a number of pixels of padding to add the beginning or end of a domain. This prop is useful for explicitly spacing data elements farther from the beginning or end of a domain to prevent axis crowding. When given as a single number, `domainPadding` will be applied to the upper and lower bound of both the x and y domains. This prop may also be given as an object with numbers or two-element arrays specified for x and y. When specifying arrays for `domainPadding`, the first element of the array will specify the padding to be applied to domain minimum, and the second element will specify padding the be applied to domain maximum.

note: The `x` value supplied to the `domainPadding` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

examples:

- `domainPadding={20}`
- `domainPadding={{x: [20, 0]}}`

note: Values supplied for `domainPadding` will be coerced so that padding a domain will never result in charts including an additional quadrant. For example, if an original domain included only positive values, `domainPadding` will be coerced so that the resulted padded domain will not include negative values.

##
eventKey

`type: string || integer || array[string] || function`

The `eventKey` prop is used to assign eventKeys to data. This prop operates identically to the x and y data accessor props. By default, the eventKey of each datum will be equal to its index in the data array. This prop is not commonly used.

See the Events Guide for more information on defining events and using event keys.

##
events

`type: array[object]`

The `events` prop takes an array of event objects. Event objects are composed of identifying properties, and `eventHandlers`.

Identifying properties include:

- `childName`: the name of the component the event should be attached to. When events are specified in `VictorySharedEvents` or on a component that renders several Victory components as children (i.e. `VictoryChart`, `VictoryGroup`, `VictoryStack`), it is necessary to specify which child events should apply to. The given `childName` should match the `name` prop of a child component. This identifier can be given as a string, an array of strings, or as "all".

- `target`: the type of element the event should be attached to. Valid targets for most Victory components will be `"parent"`, `"data"`, and `"labels"`. Events with the "parent" target will be attached to to the top level svg. Events with `"data"` and `"labels"` targets will be attached to `dataComponent` and `labelComponent` elements respectively. Some components, like `VictoryAxis` use non-standard targets like `"grid"`. Refer to individual API docs for additional caveats.

- `eventKey`: the specific element to be targeted. Events may be attached to specific elements by `eventKey`. By default, `eventKey` corresponds to the index in the `data` array (or `tickValues` array) corresponding to a rendered element. This value may be given as a single string or number, an array of strings or numbers, or as "all". It is not typically necessary to specify an individual `eventKey` for attaching events. When no `eventKey` is given, events will be attached to all elements that match a given `childName` and `target`. Some components like `VictoryArea` and `VictoryLine` render only a single element for an entire series of data. For these, the `eventKey` should be "all".

`eventHandlers` should be given as an object whose keys are standard event names (e.g., `onClick`) and whose values are event callbacks. Callbacks are called with the props of the individual element that triggered the event. For example, when a click event occurs on a bar, the props object supplied to the `onClick` handler will include props specific to that individual bar, such as `datum`, `index`, `style`, etc. Return values from event handler callbacks may be used to mutate other elements.

Event returns should be given as an array of objects composed of identifying properties for specifying the element(s) to be modified and a `mutation` function. Identifying properties include `childName`, `target`, and `eventKey`. When these values are not provided, the identifiers of the element that triggered the event will be used, including the specific `eventKey`. The `mutation` function will be called with the calculated props for each element that should be modified (e.g., a bar label), and the object returned from the mutation function will override the props of that element via object assignment.

##
externalEventMutations

`type: array[object]`

Occasionally is it necessary to trigger events in Victory's event system from some external element such as a button or a form field. Use the `externalEventMutation` prop to specify a set of mutations to apply to a given chart. The `externalEventMutations` should be given in the following form:

    externalEventMutations: PropTypes.arrayOf(
      PropTypes.shape({
        callback: PropTypes.function,
        childName: PropTypes.oneOfType([PropTypes.string, PropTypes.array]),
        eventKey: PropTypes.oneOfType([
          PropTypes.array,
          CustomPropTypes.allOfType([
            CustomPropTypes.integer,
            CustomPropTypes.nonNegative
          ]),
          PropTypes.string
        ]),
        mutation: PropTypes.function,
        target: PropTypes.oneOfType([PropTypes.string, PropTypes.array])
      })
    );

The `target`, `eventKey`, and `childName` (when applicable) must always be specified. The `mutation` function will be called with the current props of the element specified by the `target`, `eventKey` and `childName` provided. The mutation function should return a mutation object for that element. The `callback` prop should be used to clear the `externalEventMutations` prop once the mutation has been applied. Clearing `externalEventMutations` is crucial for charts that animate.

Note External mutations are applied to the same state object that is used to control events in Victory, so depending on the order in which they are triggered, external event mutations may override mutations caused by internal Victory events or vice versa.

##
groupComponent

`type: element`

The `groupComponent` prop takes a component instance which will be used to create group elements for use within container elements. For most components, this prop defaults to a `<g>` tag. Continuous data components like `VictoryLine` and `VictoryArea` use VictoryClipContainer a component which renders a `<g>` tag with a `clipPath` `def`. This allows continuous data components to transition smoothly when new data points enter and exit. `VictoryClipContainer` may also be used with components like `VictoryScatter` to prevent data from overflowing the chart area.

##
height

`type: number`

The `height` prop determines the height of the containing `<svg>`. By default Victory components render responsive containers with the `viewBox` attribute set to `viewBox="0, 0, width, height"` and `width="100%"`, `height="auto"`. In responsive containers, the `width` and `height` props affect the aspect ratio of the rendered component, while the absolute width and height are determined by the container. To render a static container, pass `responsive={false}` to the `containerComponent` like `containerComponent={<VictoryContainer responsive={false}/>}`, or set `standalone={false}` and render the resulting `<g>` tag in your own `<svg>` container. When a component is nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` setting the `height` prop on the child component will have no effect.

default (provided by default theme): `height={300}`

##
horizontal

`type: boolean`

The horizontal prop determines whether data will be plotted horizontally. When this prop is set to true, the independent variable will be plotted on the y axis and the dependent variable will be plotted on the x axis.

##
labelComponent

`type: element`

The `labelComponent` prop takes a component instance which will be used to render labels for the component. The new element created from the passed `labelComponent` will be supplied with the following properties: x, y, index, data, datum, verticalAnchor, textAnchor, angle, style, text, and events. Any of these props may be overridden by passing in props to the supplied component, or modified or ignored within the custom component itself. If `labelComponent` is omitted, a new VictoryLabel will be created with the props described above. VictoryTooltip is commonly used as a `labelComponent`

examples:

- `labelComponent={<VictoryLabel dy={20}/>}`
- `labelComponent={<VictoryTooltip/>}`

default: `<VictoryLabel/>`

##
labels

`type: array || function`

The `labels` prop defines the labels that will appear above each point. This prop should be given as an array or as a function. When given as a function, `labels` will be called with a single argument: an object containing all the props supplied to the label component. A full list of props that will be passed to `VictoryLabel` is given here.

examples:

- `labels={["first", "second", "third"]}`
- `labels={({ datum }) => datum.y}`

##
maxDomain

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

The `maxDomain` prop defines a maximum domain value for a chart. This prop is useful in situations where the maximum domain of a chart is static, while the minimum value depends on data or other variable information. If the `domain` prop is set in addition to `maximumDomain`, `domain` will be used.

note: The `x` value supplied to the `maxDomain` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

examples:

- `maxDomain={0}`
- `maxDomain={{ y: 0 }}`

##
minDomain

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

The `minDomain` prop defines a minimum domain value for a chart. This prop is useful in situations where the minimum domain of a chart is static, while the maximum value depends on data or other variable information. If the `domain` prop is set in addition to `minimumDomain`, `domain` will be used.

note: The `x` value supplied to the `minDomain` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

examples:

- `minDomain={0}`
- `minDomain={{ y: 0 }}`

##
name

`type: string`

The `name` prop is used to reference a component instance when defining shared events.

example: `name="series-1"`

##
origin

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

The origin prop is used to define the center point in svg coordinates for polar charts. All children within a polar chart must share the same origin, so setting this prop on children nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` will have no effect. When this prop is not set, it will be calculated based on the `width`, `height` and `padding` of the chart. This prop is usually not set manually.

##
padding

`type: number || { top: number, bottom: number, left: number, right: number }`

The `padding` prop specifies the amount of padding in number of pixels between the edge of the chart and any rendered child components. This prop can be given as a number or as an object with padding specified for top, bottom, left and right. As with width and height, the absolute padding will depend on whether the component is rendered in a responsive container. When a component is nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` setting `padding` on the child component will have no effect.

examples:

- `padding={{top: 20, bottom: 60}}`
- `padding={40}`

default (provided by default theme): `padding={50}`

##
polar

`type: boolean`

The boolean `polar` prop specifies whether a chart should be plotted on a polar coordinate system. All components in a given chart must share the same coordinate system, so setting this prop on children nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` will have no effect.

##
range

`type: array[low, high] || { x: [low, high], y: [low, high] }`

The `range` prop describes the dimensions over which data may be plotted. For cartesian coordinate systems, this corresponds to minimum and maximum svg coordinates in the x and y dimension. In polar coordinate systems this corresponds to a range of angles and radii. When this value is not given it will be calculated from the `width`, `height`, and `padding`, or from the `startAngle` and `endAngle` in the case of polar charts. All components in a given chart must share the same range, so setting this prop on children nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` will have no effect. This prop is usually not set manually.

examples:

- Cartesian: `range={{ x: [50, 250], y: [50, 250] }}`
- Polar: `range={{ x: [0, 360], y: [0, 250] }}`

##
samples

`type: number`

The `samples` prop specifies how many individual points to plot when plotting y as a function of x. The `samples` prop is ignored if `data` is supplied in props.

default: `samples={50}`

##
scale

`type: scale || { x: scale, y: scale }`

The `scale` prop determines which scales your chart should use. This prop can be given as a string specifying a supported scale ("linear", "time", "log", "sqrt"), or as an object with scales specified for x and y. For "time" scales, data points should be `Date` objects or `getTime()` instances.

note: The `x` value supplied to the `scale` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

default: `scale="linear"`

examples:

- `scale="time"`
- `scale={{x: "linear", y: "log"}}`

##
sharedEvents

The `sharedEvents` prop is used to coordinate events between Victory components using `VictorySharedEvents`. This prop should not be set manually.

##
singleQuadrantDomainPadding

`type: boolean || { x: boolean, y: boolean }`

By default `domainPadding` is coerced to existing quadrants. This means that if a given domain only includes positive values, no amount of padding applied by `domainPadding` will result in a domain with negative values. This is the desired behavior in most cases. For users that need to apply padding without regard to quadrant, the `singleQuadrantDomainPadding` prop may be used. This prop may be given as a boolean or an object with boolean values specified for "x" and/or "y". When this prop is false (or false for a given dimension), padding will be applied without regard to quadrant. If this prop is not specified, `domainPadding` will be coerced to existing quadrants.

note: The `x` value supplied to the `singleQuadrantDomainPadding` prop refers to the independent variable, and the `y` value refers to the dependent variable. This may cause confusion in horizontal charts, as the independent variable will corresponds to the y axis.

examples:

- `singleQuadrantDomainPadding={false}`
- `singleQuadrantDomainPadding={{ x: false }}`

##
sortKey

`type: string || integer || array[string] || function`

Use the `sortKey` prop to indicate how data should be sorted. This prop is given directly to the lodash sortBy function to be executed on the final dataset.

This prop can be provided in a variety of formats

string: specify which property in a data object to sort the data array by

    sortKey = "x";

function: use a function to determine how to sort data elements in an array

    sortKey={(datum) => datum.xValue + datum.error}

array index: specify which index of an array should be used to sort data when data is given as an array of arrays

    sortKey={0}

array: specify multiple properties to sort by

    sortKey={["age", "height"]}

##
sortOrder

`type: "ascending" || "descending"`

The `sortOrder` prop specifies whether sorted data should be returned in ascending or descending order.

default: `sortOrder="ascending"`

##
standalone

`type: boolean`

The `standalone` props specifies whether the component should be rendered in a independent `<svg>` element or in a `<g>` tag. This prop defaults to true, and renders an `svg`, however, wrapper components like `VictoryChart`, `VictoryStack`, and `VictoryGroup` force children to use `standalone={false}`.

default: `standalone={true}`

##
style

`type: object`

The `style` prop defines the style of the component. The style prop should be given as an object with styles defined for `data`, `labels` and `parent`. Any valid svg styles are supported, but `width`, `height`, and `padding` should be specified via props as they determine relative layout for components in VictoryChart.

    style={{
      data: { fill: "tomato", opacity: 0.7 },
      labels: { fontSize: 12 },
      parent: { border: "1px solid #ccc" }
    }}

Any style attribute may also be defined as a function of the props for whatever element it applies to. For example:

    style={{
      data: { fill: ({ datum }) => datum.y > 0 ? "green" : "red" },
      labels: { fontSize: ({ text }) => text.length > 10 ? 8 : 12 },
      parent: { border: "1px solid #ccc" }
    }}

note: The `style` prop used by `VictoryAxis` has a different format than the standard `style` prop.

note: When a component is rendered as a child of another Victory component, or within a custom `<svg>` element with `standalone={false}` parent styles will be applied to the enclosing `<g>` tag. Many styles that can be applied to a parent `<svg>` will not be expressed when applied to a `<g>`.

note: custom `angle` and `verticalAnchor` properties maybe included in labels styles.

default (provided by default theme): See grayscale theme for more detail

##
theme

`type: object`

The `theme` prop specifies a theme to use for determining styles and layout properties for a component. Any styles or props defined in `theme` may be overwritten by props specified on the component instance. By default, components use a grayscale theme.

See the Themes Guide for information about creating custom themes.

default: `theme={VictoryTheme.grayscale}`

    theme={VictoryTheme.material}

##
width

`type: number`

The `width` prop determines the width of the containing `<svg>`. By default Victory components render responsive containers with the `viewBox` attribute set to `viewBox="0, 0, width, height"` and `width="100%"`, `height="auto"`. In responsive containers, the `width` and `height` props affect the aspect ratio of the rendered component, while the absolute width and height are determined by the container. To render a static container, pass `responsive={false}` to the `containerComponent` like `containerComponent={<VictoryContainer responsive={false}/>}`, or set `standalone={false}` and render the resulting `<g>` tag in your own `<svg>` container. When a component is nested within `VictoryChart`, `VictoryStack`, or `VictoryGroup` setting `width` prop on the child component will have no effect.

default (provided by default theme): `width={450}`

##
x

`type: string || integer || array[string] || function`

Use the `x` data accessor prop to determine how the component defines data in the x dimension. This prop may be given in a variety of formats:

string: specify which property in an array of data objects should be used as the x value

    x = "month";

function: use a function to translate each element in a data array into an x value

    x={(datum) => datum.xValue + datum.error}

array index: specify which index of an array should be used as an x value when data is given as an array of arrays

    x={0}

path string or path array: specify which property in an array of nested data objects should be used as an x value

    x="employees.name"`, `x={["employees", "name"]}

See the Data Accessors Guide for more detail on formatting and processing data.

##
y

`type: string || integer || array[string] || function`

Use `y` data accessor prop to determine how the component defines data in the y dimension. This prop may be given in a variety of formats:

string: specify which property in an array of data objects should be used as the y value

    y = "profit";

function: use a function to translate each element in a data array into a y value

    y={(datum) => Math.sin(2 * Math.PI * datum.x)}

array index: specify which index of an array should be used as a y value when data is given as an array of arrays

    y={1}

path string or path array: specify which property in an array of nested data objects should be used as a y value

    y="employees.salary"`, `y={["employees", "salary"]}

See the Data Accessors Guide for more detail on formatting and processing data.

##
y0

`type: string || integer || array[string] || function`

Use `y0` data accessor prop to determine how the component defines the baseline y0 data. This prop is useful for defining custom baselines for components like `VictoryBar` or `VictoryArea`. This prop may be given in a variety of formats.

string: specify which property in an array of data objects should be used as the y0 value

    y0 = "last_quarter_profit";

function: use a function to translate each element in a data array into a y0 value

    y0={() => 10}

array index: specify which index of an array should be used as a y0 value when data is given as an array of arrays

    y0={1}

path string or path array: specify which property in an array of nested data objects should be used as a y0 value

    y0="employees.salary"`, `y={["employees", "salary"]}

See the Data Accessors Guide for more detail on formatting and processing data.