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
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.
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. Nest child components within the
VictorySharedEvents wrapper, and reference them as you would when using
External Event Mutations
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:
childName: PropTypes.oneOfType([PropTypes.string, PropTypes.array]),
target: PropTypes.oneOfType([PropTypes.string, PropTypes.array])
childName (when applicable) must always be specified. The
mutation function will be called with the current props of the element specified by the
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.
Events on Custom Components
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.