Preparing a .riv

A banner can play a Rive animation: a bell that rings when new mail arrives, a spinner while a job runs, an icon that reacts to the mouse. This page is for anyone who makes the animation or writes the template that plays it. It covers how to prepare a .riv file, how to get it into Herald, how notification fields and the mouse drive it, and how to find out why it does not play. The properties of the component itself are in the rive component reference.

Examples use the fictional app example.bidbot unless a section says otherwise, and the $HERALD and $TOKEN variables from Connect.

What Herald does with a Rive file#

A rive component draws one artboard of a .riv file inside one cell of a banner and keeps it playing while the banner is up. Read this section first to learn what you can and cannot ask of an animation.

Herald does these things for every rive component:

1. It loads the file and picks an artboard and a state machine.
2. It plays the state machine with contain fit, centred, and starts it at once.
3. It writes the state machine's inputs (Number, Boolean and Trigger) from the notification's fields and from the mouse (hover and pressed).
4. It optionally runs an action when the animation is clicked.

Rive's own features go further than this. Herald does not use these, so design the animation without them:

The next sections follow the order of the work: prepare the file, store it, reference it, drive it, size it.

Preparing the file in the Rive editor#

Herald reads three things from your file: the artboard, the state machine and its inputs. This section lists what to set in the Rive editor so that each one behaves well in a banner.

Artboard#

Square artboards of 64 x 64 or 128 x 128 suit icon-sized animations, where the box is typically 24 to 48 points high. A strip such as 400 x 120 suits a banner-wide animation. With no artboard name in the component, Herald plays the file's default (first) artboard.

State machine#

Create a state machine and give it a name such as Main. Herald chooses the one to play in this order:

1. The component's stateMachine.
2. The stateMachine of the manifest asset the component names.
3. The artboard's default state machine.
4. The first state machine in the artboard.

A file with no state machine but with a linear animation plays the first animation, and the component's loop chooses between looping and playing once. A file with neither shows the placeholder the file has no state machine or animation. Naming a state machine that does not exist is an error, and the message lists the names that do exist.

Inputs#

Herald supports the three input types a state machine has:

Inputs are found by name, and the match is case-sensitive.

• A binding whose name is not an input of the state machine is skipped without an error, so a typo is silent.
• Run a check and read the inputs it reports to see which names Herald found.
• Name inputs after what the field means, not how it looks: count, isUnread, ring, progress.

Hover, press and click#

Three different things can react to the pointer. Each is wired in the template, not in the file:

How the pointer reaches the animation:

• A Boolean input bound to hover is true while the pointer is inside. A Number input gets 1 or 0. A Trigger fires when the pointer enters.
• pressed works the same way with the mouse button. Leaving the animation while pressed releases it.
• Hover tracking works in the banner, which never takes focus.
• Mouse down, drag and up are passed to Rive, so a state machine's own pointer listeners for press, drag and release work.
• Pointer move is not passed to Rive. A Rive "pointer enter", "exit" or "move" listener does not fire. Use a hover input instead.
• Without an action, an actionRef or a pressed binding, the animation lets clicks through to the banner, so clicking it still does what clicking the banner does. Banner clicks are described in How banners behave.

A rive cell is never treated as empty, because it always has an asset or a path, so it is always drawn. To show the animation only for some notifications, use a second template, or make the state machine's idle state invisible and bind an input to a field.

Images and fonts inside the file#

Assets embedded in the .riv always work. Assets the file marks as hosted elsewhere are fetched from the network when the animation loads, which delays the banner and fails offline. For a banner that must appear instantly and work offline, embed every asset in Rive by choosing Embed in the asset's export settings. The Designer reads the file only for names and inputs and does not fetch hosted assets.

File size and count#

A banner loads its animation every time it appears, so keep files small. Under 100 KB is typical for icon-sized work. The 10 MB limit is a ceiling, not a target.