DEPRECATION NOTICE: This entire page documents the legacy Text
manipulation system. For new projects: Use Data Binding instead. For existing projects: Plan to
migrate from direct text run manipulation to Data Binding as soon as possible. Read/Update Text Runs at Runtime
⚠️ LEGACY CONTENT WARNING: The following sections document the deprecated
Text manipulation system. This content is provided for legacy support
only. New implementations should use Data Binding. 
And then export the name: right-click and select Export name
You can identify an exported component if it’s surrounded by square brackets. This makes it possible for the run to be “discoverable” at runtime by its name. For more information, see Exporting for Runtime.
If the name is not set manually in the editor the name will not be part of
the exported .riv (to reduce file size).
Examples
High-level API usage
Reading Text
To read a given text run text value at any given time, reference the .getTextRunValue() API on the Rive instance:
public getTextRunValue(textRunName: string): string | undefined
undefined if the text run could not be queried.
Setting Text
To set a given text run value at any given time, reference the .setTextRunValue() API on the Rive instance:
public setTextRunValue(textRunName: string, textRunValue: string): void
textValue, with a String value that you want to set the new text value for if the text run can be successfully queried on the active artboard.
Example Usage
import {Rive} from '@rive-app/canvas'
const r = new Rive({
src: "my-rive-file.riv"
artboard: "my-artboard-name",
autoplay: true,
stateMachines: "State Machine 1",
onLoad: () => {
console.log("My design-time text is, ", r.getTextRunValue("MyRun"));
r.setTextRunValue("MyRun", "New text value");
},
})
Low-level API usage
Get a reference to the Rive Artboard, find a text run by a given name, and get/update the text value property.
import RiveCanvas from '@rive-app/canvas-advanced';
const bytes = await (
await fetch(new Request('./my-rive-file.riv'))
).arrayBuffer();
const myRiveFile = await rive.load(new Uint8Array(bytes));
const artboard = myRiveFile.defaultArtboard();
const textRun = artboard.textRun("MyRun"); // Query by the text run name
console.log(`My design-time text is ${textRun.text}`);
textRun.text = "Hello JS Runtime!";
...
Read/Update Nested Text Runs at Runtime
⚠️ DEPRECATED FEATURE: Nested Text Runs are part of the legacy Text
manipulation system. Use Data Binding instead for controlling component
text properties at runtime.
Setting Nested Text Runs
The artboard names here are:
- Main -> NestedArtboard -> Button
However, the path is determined based on the names set in the hierarchy:
- ArtboardWithUniqueName -> ButtonWithUniqueName
The path is then: ArtboardWithUniqueName/ButtonWithUniqueName
Be sure to mark the components and text runs as exported.
Export
component name Do not use ”/” in the name for your components, as that will break the search
functionality at runtime.
Examples
High-level API usage
Reading Text
To read a given text run text value at a specific path, reference the .getTextRunValueAtPath() API on the Rive instance:
public getTextRunValueAtPath(textRunName: string, path: string): string | undefined
undefined if the text run could not be queried.
Setting Text
To set a given text run value at a specific path, reference the .setTextRunValueAtPath() API on the Rive instance:
public setTextRunValueAtPath(textRunName: string, textRunValue: string, path: string): void
textRunName, the new textValue, and the path where the run is located at a component instance level.
Example Usage
import {Rive} from '@rive-app/canvas'
const r = new Rive({
src: "my-rive-file.riv"
artboard: "my-artboard-name",
autoplay: true,
stateMachines: "State Machine 1",
onLoad: () => {
console.log("My design-time text is, ", r.getTextRunValueAtPath("MyRun", "path/to/run"));
r.setTextRunValueAtPath("MyRun", "New text value", "path/to/run");
},
})
Semantics for Accessibility
We recommend using Data Binding instead as
you’ll be able to do a two way text binding. Adding ARIA Label
At a minimum - if it is important to convey the text value displayed in the Rive animation to all users, add an aria-label to the <canvas> element with the text value from the animation. Screen readers may read this label out immediately as it parses out the DOM contents. You’ll also want to add role="img" to the <canvas> element as well.
<canvas
id="rive-canvas"
width={500}
height={500}
role="img"
aria-label="Hello friend, welcome to my page"
></canvas>
Adding ARIA Live Region
While ARIA labels are a direct method to manage a textual label for screen readers to read out as it parses web content, using an ARIA live region allows you a way to control when screen readers read out dynamic text content.
Live regions are useful in cases where the text content in your Rive graphic becomes visible or changes on a particular state in a state machine, and you want screen readers to pick up on text changes. Another use case is when you only want screen readers to read your Rive text content when the <canvas> is scrolled into view.
Read more on ARIA live regions here.
Example: Rating Graphic
Imagine you’re displaying an interactive Rive graphic that allows users to choose a rating from 1-5 stars. Users clicking on the different stars can visually see the state machine in action with animations to see what star they click, but screen readers may need a way to announce what selection was chosen as other users navigate the canvas with keyboard controls, for example.
The HTML for this might look like the following:
<canvas
role="img"
tabindex="0"
aria-describedby="rating-animation-live"
id="canvas"
></canvas>
<p id="rating-animation-live" class="sr-only" aria-live="assertive">
An interactive rating simulation. Use the left and right arrow keys to
select a rating
</p>
<canvas> element has an aria-describedby attribute whose value matches the id of the <p> below it, #rating-animation-live. This allows the <p> block content to describe the <canvas> element. And similar to using aria-label, we have to add the role="img" attribute to the canvas as well. The aria-live="assertive" attribute describes how to interrupt the screen reader’s flow of reading content based on when the content within this <p> changes.
Let’s take a look at what the JS might look like using the Rive Web (JS) runtime:
const rive = require("@rive-app/canvas");
const dynamicTextEl = document.getElementById("rating-animation-live");
const r = new rive.Rive({
src: "rating.riv",
canvas: document.getElementById("canvas"),
stateMachines: "State Machine 1",
autoplay: true,
onLoad: () => {
r.setTextRunValue("RatingRun", "0");
r.resizeDrawingSurfaceToCanvas();
// See CodeSandbox link above for further functionality
},
onStateChange: (e) => {
const name = e.data[0];
const ratingStr = name.charAt(0);
const ratingNum = parseInt(ratingStr);
if (!isNaN(ratingNum)) {
const ratingString = name
.split("_")
.reduce((acc, temp) => {
return (acc += ` ${temp}`);
}, "")
.trim();
r.setTextRunValue("RatingRun", ratingStr);
dynamicTextEl.innerHTML = `Rating: ${ratingString}`;
}
}
});
dynamicTextEl) with the string rating. Due to the live region having the property of aria-live="assertive", screen readers should read off the new dynamic text content.
Additional Resources:
