Skip to main content

​
Overview

RiveArtboard represents a single artboard within a Rive file. An artboard is a container for animations, state machines, and graphics. It provides methods for accessing animations, state machines, text runs, and controlling playback.

​
Properties

​
volume
float
required
Audio volume for the artboard. Ranges from 0.0 (muted) to 1.0 (full volume).
​
didChange
BOOL
required
Indicates whether the artboard has changed since the last frame (read-only).

​
Artboard Information

​
name

Returns the name of the artboard.
​
return
NSString*
required
The artboard’s name.
- (NSString*)name;

​
bounds

Returns the bounds of the artboard.
​
return
CGRect
required
The artboard’s bounds as a CGRect.
- (CGRect)bounds;

​
Dimensions

​
width

Returns the width of the artboard.
​
return
double
required
The artboard’s width.
- (double)width;

​
height

Returns the height of the artboard.
​
return
double
required
The artboard’s height.
- (double)height;

​
setWidth:

Sets the width of the artboard.
​
value
double
required
The new width value.
- (void)setWidth:(double)value;

​
setHeight:

Sets the height of the artboard.
​
value
double
required
The new height value.
- (void)setHeight:(double)value;

​
resetArtboardSize

Resets the artboard to its original size as defined in the Rive file. 
- (void)resetArtboardSize;

​
State Machine Inputs

​
getBool:path:

Retrieves a boolean input from a state machine.
​
name
NSString*
required
The name of the boolean input.
​
path
NSString*
required
The path to the nested artboard containing the input.
​
return
const RiveSMIBool*
required
The boolean input, or nil if not found.
- (const RiveSMIBool*)getBool:(NSString*)name path:(NSString*)path;

​
getTrigger:path:

Retrieves a trigger input from a state machine.
​
name
NSString*
required
The name of the trigger input.
​
path
NSString*
required
The path to the nested artboard containing the input.
​
return
const RiveSMITrigger*
required
The trigger input, or nil if not found.
- (const RiveSMITrigger*)getTrigger:(NSString*)name path:(NSString*)path;

​
getNumber:path:

Retrieves a number input from a state machine.
​
name
NSString*
required
The name of the number input.
​
path
NSString*
required
The path to the nested artboard containing the input.
​
return
const RiveSMINumber*
required
The number input, or nil if not found.
- (const RiveSMINumber*)getNumber:(NSString*)name path:(NSString*)path;

​
Animations

​
animationCount

Returns the number of animations in the artboard.
​
return
NSInteger
required
The number of animations.
- (NSInteger)animationCount;

​
animationNames

Returns the names of all animations in the artboard.
​
return
NSArray<NSString*>*
required
Array of animation names.
- (NSArray<NSString*>*)animationNames;

​
animationFromIndex:error:

Returns an animation instance by its index.
​
index
NSInteger
required
Zero-based index of the animation.
​
error
NSError**
required
Pointer to an error object that will be set if the operation fails.
​
return
RiveLinearAnimationInstance*
required
The animation instance at the specified index, or nil if an error occurs.
- (RiveLinearAnimationInstance* __nullable)animationFromIndex:(NSInteger)index
                                                        error:(NSError**)error;

​
animationFromName:error:

Returns an animation instance by its name.
​
name
NSString*
required
Name of the animation as defined in the Rive file.
​
error
NSError**
required
Pointer to an error object that will be set if the operation fails.
​
return
RiveLinearAnimationInstance*
required
The animation instance with the specified name, or nil if an error occurs.
- (RiveLinearAnimationInstance* __nullable)animationFromName:(NSString*)name
                                                       error:(NSError**)error;

​
State Machines

​
stateMachineCount

Returns the number of state machines in the artboard.
​
return
NSInteger
required
The number of state machines.
- (NSInteger)stateMachineCount;

​
stateMachineNames

Returns the names of all state machines in the artboard.
​
return
NSArray<NSString*>*
required
Array of state machine names.
- (NSArray<NSString*>*)stateMachineNames;

​
stateMachineFromIndex:error:

Returns a state machine instance by its index.
​
index
NSInteger
required
Zero-based index of the state machine.
​
error
NSError**
required
Pointer to an error object that will be set if the operation fails.
​
return
RiveStateMachineInstance*
required
The state machine instance at the specified index, or nil if an error occurs.
- (RiveStateMachineInstance* __nullable)stateMachineFromIndex:(NSInteger)index
                                                        error:(NSError**)error;

​
stateMachineFromName:error:

Returns a state machine instance by its name.
​
name
NSString*
required
Name of the state machine as defined in the Rive file.
​
error
NSError**
required
Pointer to an error object that will be set if the operation fails.
​
return
RiveStateMachineInstance*
required
The state machine instance with the specified name, or nil if an error occurs.
- (RiveStateMachineInstance* __nullable)stateMachineFromName:(NSString*)name
                                                       error:(NSError**)error;

​
defaultStateMachine

Returns the default state machine for the artboard.
​
return
RiveStateMachineInstance*
required
The default state machine instance, or nil if none exists.
- (RiveStateMachineInstance* __nullable)defaultStateMachine;

​
Text Runs

​
textRun:

Retrieves a text run by name.
​
name
NSString*
required
The name of the text run.
​
return
RiveTextValueRun*
required
The text run, or nil if not found.
- (RiveTextValueRun* __nullable)textRun:(NSString*)name;

​
textRun:path:

Retrieves a text run by name and path.
​
name
NSString*
required
The name of the text run.
​
path
NSString*
required
The path to the nested artboard containing the text run.
​
return
RiveTextValueRun*
required
The text run, or nil if not found.
- (RiveTextValueRun* __nullable)textRun:(NSString*)name path:(NSString*)path;

​
Playback and Rendering

​
advanceBy:

Advances the artboard’s animation state by the specified time.
​
elapsedSeconds
double
required
The time in seconds to advance the animation.
- (void)advanceBy:(double)elapsedSeconds;

​
draw:

Draws the artboard using the specified renderer.
​
renderer
RiveRenderer*
required
The renderer to use for drawing.
- (void)draw:(RiveRenderer*)renderer;

​
Data Binding

​
bindViewModelInstance:

Binds an instance of a view model to the artboard for updates. A strong reference to the instance being bound must be made if you wish to reuse instance properties or for observability. The same instance must also be bound to a state machine, if one exists.
​
instance
RiveDataBindingViewModelInstance*
required
The instance of a view model to bind.
- (void)bindViewModelInstance:(RiveDataBindingViewModelInstance*)instance
    NS_SWIFT_NAME(bind(viewModelInstance:));

​
Example Usage

// Get artboard from file
NSError* error = nil;
RiveArtboard* artboard = [file artboard:&error];

// Get artboard dimensions
double width = [artboard width];
double height = [artboard height];

// Get animation by name
RiveLinearAnimationInstance* animation = [artboard animationFromName:@"idle" error:&error];

// Get state machine
RiveStateMachineInstance* stateMachine = [artboard stateMachineFromName:@"State Machine 1" error:&error];

// Advance artboard animation
[artboard advanceBy:deltaTime];

// Draw artboard
[artboard draw:renderer];

Build docs developers (and LLMs) love

Get started for freeTalk to us