Events

Victory uses a flexible event system that is agnostic of event type. Browser events like onClick are handled identically to mobile touch events like onPressIn. Victory's event system allows users to attach events to any rendered element, and trigger mutations on any other rendered element.

This guide will demonstrate how to use Victory's event system within a single component, between several components nested within wrapper components like VictoryChart or VictoryGroup, and between several components using the VictorySharedEvents wrapper. This guide will also explain how to bypass Victory's event system entirely, and attach simple events directly to rendered components.

Events within a single component like VictoryBar may be defined by the events prop of the component. The component will be responsible for storing event-driven mutations on its state object. The events prop should be given as an array of event objects. Each object defines an event or set of events to attach to a particular target element, or set of target elements.

Target elements are specified by the target and eventKey properties. Valid target properties match the namespaces of the style element of any given component. For most components valid target properties are "data", "labels", and "parent". The target property is required. The optional eventKey property may be given as a value or array of values.

Events are defined by the eventHandlers property which should be given as an object whose properties are named events such as onClick, and whose values are event handlers. Event handlers are called with the event, the props defining the element that triggered the event, and the event key of the element that triggered the event.

Return values from event handlers are used to define mutations affecting rendered elements. Return values from event handlers should be given as an array of mutation objects. Mutation objects may have target and eventKey properties to specify an element to mutate. If these properties are not given, the mutation will effect the element that triggered the event. Mutation objects should also have a mutation property whose value is a function. The mutation function will be called with the event, the props defining the element that will be mutated, and the event key of the element that will be mutated. The mutation function should return an object of props to be modified, and the new values for those props.

In the example below, clicking on any of the bars will trigger a change in the text of the corresponding labels.

Wrapper components like VictoryChart, VictoryGroup, and VictoryStack may define events for their children. Component events defined by wrappers operate much the same as single component events, except that the events are defined on the parent component, and event-driven mutations are stored in the parent's state. Events on child components are specified with the childName property. Components that have a name prop specified will be referenced by name. If child components do not have a name specified they will be referenced by index. In the example below, clicking on either of the bottom two areas in the stack will change the color of the top area.

Components like VictoryChart use the VictorySharedEvents wrapper automatically, but the wrapper may also be used on its own. Nest child components within the VictorySharedEvents wrapper, and reference them as you would when using VictoryChart

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.func,
    childName: PropTypes.oneOfType([PropTypes.string, PropTypes.array]),
    eventKey: PropTypes.oneOfType([
      PropTypes.array,
      CustomPropTypes.allOfType([CustomPropTypes.integer, CustomPropTypes.nonNegative]),
      PropTypes.string
    ]),
    mutation: PropTypes.func,
    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.

For simple events, it may be desirable to bypass Victory's event system. To do so, specify events props directly on primitive components rather than using the events prop on Victory components. The simple events prop should be given as an object whose properties are event names like onClick, and whose values are event handlers. Events specified this way will only be called with the standard event objects.

For custom SVG components, Victory's event system is not the only option. It's possible to bypass it altogether in favor of using native React events on the custom SVG components. This might be preferable when lots of custom styling and interactions are needed.

Notice how the circle component in this example is a basic SVG element with React event props rather than a Victory component.