Rive Events
Subscribing to Rive Events at runtime.
With Rive events, you have the ability to subscribe to meaningful signals that get reported from animations, state machines, and Rive listeners, all created at design time from the Rive editor. These signals can be subscribed to at runtime and have a specific name, type, and various custom metadata that may accompany the event to help inform the context surrounding its meaning.
For more on the Events feature in general, check out the Events page in the editor section of the docs. The Event system has also been expanded to support Audio Events to trigger audio to play in the editor and at runtime.
For example, in a Rive graphic simulating a loader, there may be an event named LoadComplete
fired when transitioning from a complete
timeline animation state to an idle
state. You can subscribe to Rive events with a callback that the runtime may invoke, and from there, your callback can handle extra functionality at just the right moment when the event fired.
Other practical use cases for events:
- Coordinating audio playback at specific moments in an animation, see Audio Events
- Opening a URL when specific interactions have occurred
- Adding haptic feedback on meaningful touch interactions
- Implementing functionality on Buttons and other UI elements
- Send semantic information
- Communicate any information your runtime needs at the right moment
Subscribing to Events
When you subscribe to Rive events at runtime, you subscribe to all Rive events that may be emitted from a state machine, and you can parse through each event by name or type to execute conditional logic.
Let’s use a 5-star rater Rive example to set any text supplied with events and open a URL if one is given.
Examples
- Star rating example
- Neostream example (Chrome only) (This example does not make use of the new Audio Events feature)
High-level API usage
Adding an Event Listener
Similar to the addEventListener()
/ removeEventListener()
API for DOM elements, you’ll use the Rive instance’s on()
/ off()
API to subscribe to Rive events. Simply supply the RiveEvent enum and a callback for the runtime to call at the appropriate moment any Rive event gets detected.
Example Usage
Low-level API usage
When using the low-level APIs (i.e. @rive-app/canvas-advanced
), you’ll need to catch Rive events reported during the render loop yourself via your created state machine instance (see docs on Low-level API Usage). To achieve this, before advancing the state machine:
- Determine the number of Rive events reported since the last frame via the state machine’s
reportedEventCount()
API - Iterate over the events and grab a reference to an Event via the state machine’s
reportedEventAt(idx)
API
Examples
- Star rating example
- Neostream example (Chrome only) (This example does not make use of the new Audio Events feature)
High-level API usage
Adding an Event Listener
Similar to the addEventListener()
/ removeEventListener()
API for DOM elements, you’ll use the Rive instance’s on()
/ off()
API to subscribe to Rive events. Simply supply the RiveEvent enum and a callback for the runtime to call at the appropriate moment any Rive event gets detected.
Example Usage
Low-level API usage
When using the low-level APIs (i.e. @rive-app/canvas-advanced
), you’ll need to catch Rive events reported during the render loop yourself via your created state machine instance (see docs on Low-level API Usage). To achieve this, before advancing the state machine:
- Determine the number of Rive events reported since the last frame via the state machine’s
reportedEventCount()
API - Iterate over the events and grab a reference to an Event via the state machine’s
reportedEventAt(idx)
API
Examples
Adding an Event Listener
Similar to the addEventListener()
/ removeEventListener()
API for DOM elements, you’ll use the Rive instance’s on()
/ off()
API to subscribe to Rive events from the rive
object returned from the useRive
hook. Simply supply the RiveEvent enum and a callback for the runtime to call at the appropriate moment any Rive event gets detected.
Note: You must use the useRive()
hook to subscribe to Rive events
Example Usage
Adding a Rive Event Listener
Similar to other callback functions you can provide on the <Rive>
component, such as onPlay
or onStateChange
, you can now provide an onRiveEventReceived
callback which will be invoked any time a Rive Event gets reported during the render loop.
The API signature is as follows:
Example Usage
Adding an Event Listener
After creating a StateMachineController
instance, you’ll use the addEventListener
/ removeEventListener
API and provide a callback to subscribe to Rive events.
The API signature:
You may add multiple event listener callbacks if you need to, but all event listeners need to be removed. All event listeners will be removed when the controller is disposed.
Rive’s event object provided to the callback will vary depending on the type of event (i.e. RiveGeneralEvent
vs RiveOpenURLEvent
, and others in the future). These derive from RiveEvent
which has:
name
- Name of the event.secondsDelay
- Time since the event was reported and the callback received the event.properties
- Custom properties are extra data that can be supplied with an event at design time.
The RiveOpenURLEvent
has additional fields: url
and target
(enum of type OpenUrlTarget
).
For example, a sample callback to handle logging a Rive event may look like the following:
Example Usage - Star Rating
This example demonstrates how to retrieve custom properties set on a Rive event and update a Flutter UI component.
Note that a Rive event could be triggered during a Flutter frame update. Calling setState
at this stage will result in an exception being thrown by Flutter. Instead you should schedule a setState
to be called on the next frame using WidgetsBinding.instance.addPostFrameCallback
Example Usage - Open a URL
A common action you may want to do is open a URL from a Rive Event. For that Rive provides a custom event type RiveOpenURLEvent
.
Subscribing to Events via State Machine Delegate
To subscribe to Rive events, implement the onRiveEventReceived
protocol from StateMachineDelegate
.
@objc optional func onRiveEventReceived(onRiveEvent riveEvent: RiveEvent)
This implementation may be invoked when a Rive event is fired from the render loop and provides a generic RiveEvent
data type, of which you can type check to cast to a specific event for further parsing, such as a RiveGeneralEvent
or a RiveOpenUrlEvent
.
For example:
Note: Events of type RiveOpenUrlEvent
will not automatically open links in the user’s preferred browser. You will need to add the logic to grab the url
property of the riveEvent
passed into the delegate and open the link.
Example Usage
Adding an Event Listener
Use the addEventListener
and removeEventListener
on RiveAnimationView
to subscribe/unsubscribe aRiveFileController.RiveEventListener
.
This listener receives either an OpenURLRiveEvent
or GeneralRiveEvent
of type RiveEvent
.
The Rive Android Runtime is executed on a separate thread. Any UI updates that are triggered from a Rive event will need to be manually marked to run on the UI thread using runOnUiThread
. See examples below.
Opening a URL
Events of type OpenUrlRiveEvent
will not automatically open links. The code needs to be added manually in your project.
The following is an example that demonstrates how to open a URL on Android when an OpenUrlRiveEvent
is received:
You can also access event.target
to get the target destination of the URL, as set in the editor.
Example
The following demonstrates how to update UI in response to some Rive event (named “StarRating”) that contains a custom number property (named “Rating”). Note the runOnUiThread
:
It’s possible to evaluate which event has come through by checking the name
and type of event (GeneralRiveEvent
vs OpenURLRiveEvent
).
By calling event.properties
you’ll get a HashMap
that contains any custom properties defined on the event.
Additional Resources
Was this page helpful?