Victory uses a flexible event system that is completely 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
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.
Single Component Events
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
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
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.
Events may also be targeted specific data elements or groups of data elements by event key using the
eventKey property. The
eventKey property may be given as a single value or as an array of values. If no
eventKey is specified, events will be attached to all elements of a specified target type, and mutations will affect only elements corresponding to the event key of the element that triggered the event. Element event keys may be applied directly to data objects, or set using the
eventKey data accessor prop. By default, the event key will be set to the index of the element in the data array.
eventKey is not specified in the mutation, the event mutation will target the same event key as the element that triggered the event. Similarly, if the target is not specified, the target will be assumed to be the same target type as the element that triggered the event.
Nested Component Events
Wrapper components like
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.
VictoryChart use the
VictorySharedEvents wrapper automatically, but the wrapper may also be used on its own. Simply nest child components within the
VictorySharedEvents wrapper, and reference them as you would when using
For very simple events, it may be desireable 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.