Text

⚠️ DEPRECATED: Use Data Binding instead of direct text run manipulation at runtime

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.

For more information on designing and animating Text, please refer to the editor’s text section:

Text

Information on designing and animating Text

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.

If you intend to update a text run at runtime it’s important to manually enter a unique name for the run in the editor:

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).

Text runs can also be updated on components at runtime, see Read/Update Nested Text Runs at Runtime below.

Examples

• Updating Text at Runtime - Localization example

Reading Text

To read a given text run text value at any given time, reference the .getTextRunValue() API on the rive instance returned from useRive:

public getTextRunValue(textRunName: string): string | undefined

Supply the text run name, and you’ll have the Rive text run value returned, or 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 returned from useRive:

public setTextRunValue(textRunName: string, textRunValue: string): void

Supply the text run name and a second parameter, 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 { useRive } from '@rive-app/canvas';

const MyTextComponent = () => {
const {rive, RiveComponent} = useRive({
    src: "my-rive-file.riv",
    artboard: "New Artboard",
    stateMachines: "State Machine 1",
    autoplay: true,
});

// Cannot query for the text run immediately, you have to wait until `rive`
// has value and has instantiated before querying or setting text run values
useEffect(() => {
    if (rive) {
    console.log("Rive text was initially: ", rive.getTextRunValue("MyRun"));
    rive.setTextRunValue("MyRun", "New Text!!");
    console.log("Rive text is now: ", rive.getTextRunValue("MyRun"));
    }
}, [rive]);

return (
    <RiveComponent />
);
};

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.

It’s possible to set nested text runs at runtime—text that is not on the main artboard but on a Component. To set a nested text run, you’ll need to take note of the path where the input exists at an artboard level.

For example, to get/set the text run named button_text on the Button artboard, you need to provide the correct path.

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

• Updating Text at Runtime - Localization example

Reading Text

To read a given text run text value at any given time, reference the .getTextRunValue() API on the rive instance returned from useRive:

public getTextRunValue(textRunName: string): string | undefined

Supply the text run name, and you’ll have the Rive text run value returned, or 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 returned from useRive:

public setTextRunValue(textRunName: string, textRunValue: string): void

Supply the text run name and a second parameter, 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 { useRive } from '@rive-app/canvas';

const MyTextComponent = () => {
const {rive, RiveComponent} = useRive({
    src: "my-rive-file.riv",
    artboard: "New Artboard",
    stateMachines: "State Machine 1",
    autoplay: true,
});

// Cannot query for the text run immediately, you have to wait until `rive`
// has value and has instantiated before querying or setting text run values
useEffect(() => {
    if (rive) {
    console.log("Rive text was initially: ", rive.getTextRunValue("MyRun"));
    rive.setTextRunValue("MyRun", "New Text!!");
    console.log("Rive text is now: ", rive.getTextRunValue("MyRun"));
    }
}, [rive]);

return (
    <RiveComponent />
);
};

Semantics for Accessibility

We recommend using Data Binding instead as you’ll be able to do a two-way text binding.

As Rive Text does not make use of the underlying platform text APIs, additional steps need to be taken to ensure it can be read by screen readers.

Please see the respective platform/SDKs developer documentation for additional information regarding accessibility concerns.

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.

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.

Additional Resources:

• Accessible web animations: ARIA live regions