Layout

The Fit Mode

A Rive graphic authored in the editor will not necessarily match the size of the container (canvas, view, widget, or texture) it is rendered into at runtime. We need to determine the behavior for this scenario, as no one size fits all. The solution is choosing the fit mode. This is specified on the container and controls how Rive is scaled.

Layout: Use the Rive layout engine to apply responsive layout to the artboard, matching the container dimensions. For this to work, the artboard must be designed with layouts in mind. See Responsive Layouts for more information on how to use this option.
Contain: (Default) Preserve aspect ratio and scale the artboard so that its larger dimension matches the corresponding dimension of the container. If aspect ratios are not identical, this will leave space on the shorter dimension’s axis.
ScaleDown: Preserve aspect ratio and behave like Contain when the artboard is larger than the container. Otherwise, use the artboard’s original dimensions.
Cover: Preserve aspect ratio and scale the artboard so that its smaller dimension matches the corresponding dimension of the container. If aspect ratios are not identical, this will clip the artboard on the larger dimension’s axis.
FitWidth: Preserve aspect ratio and scale the artboard width to match the container’s width. If the aspect ratios between the artboard and container do not match, this will result in either vertical clipping or space in the vertical axis.
FitHeight: Preserve aspect ratio and scale the artboard height to match the container’s height. If the aspect ratios between the artboard and container do not match, this will result in either horizontal clipping or space in the horizontal axis.
Fill: Do not preserve aspect ratio and stretch to the container’s dimensions.
None: Do not scale. Use the artboard’s original dimensions. For either dimension, if the artboard’s dimension is larger, it will be clipped. If it is smaller, it will leave space.

Alignment

In all options other than Layout and Fill, there is the possibility that the Rive graphic is clipped or leaves space within its container. Alignment determines how to align content aligns with within the container. The following options are available.

TopLeft
TopCenter
TopRight
CenterLeft
Center (Default)
CenterRight
BottomLeft
BottomCenter
BottomRight

Bounds

Some runtimes expose the option to set the bounding dimensions for the area in which the Rive content will render by providing the minimum and maximum x and y coordinates. These coordinates are relative to the container and all must be provided. These will override alignment settings.

minX
minY
maxX
maxY

Applying the Fit Mode

Use the Layout object to configure Fit and Alignment. See Fit and Alignment for all enum options.

<div>
    <canvas id="canvas" width="800" height="600"></canvas>
</div>
<script src="https://unpkg.com/@rive-app/canvas@latest"></script>
<script>
    // Fill the canvas, cropping Rive if necessary
    let layout = new rive.Layout({
        fit: rive.Fit.Cover,
    });

    // Fit to the width and align to the top of the canvas
    layout = new rive.Layout({
        fit: rive.Fit.FitWidth,
        alignment: rive.Alignment.TopCenter,
    });

    // Constrain the Rive content to (minX, minY), (maxX, maxY) in the canvas
    layout = new rive.Layout({
        fit: rive.Fit.Contain,
        minX: 50,
        minY: 50,
        maxX: 100,
        maxY: 100,
    });

    const r = new rive.Rive({
        src: 'https://cdn.rive.app/animations/vehicles.riv',
        canvas: document.getElementById('canvas'),
        layout: layout,
        autoplay: true
    });

    // Update the layout
    r.layout = new rive.Layout({ fit: rive.Fit.Fill });
</script>

Use the Layout object to configure Fit and Alignment. See Fit and Alignment for all enum options.

import Rive, { Layout, Fit, Alignment } from '@rive-app/react-canvas';

export const Simple = () => (
  <Rive
    src="https://cdn.rive.app/animations/vehicles.riv"
    layout={new Layout({ fit: Fit.Contain, alignment: Alignment.TopCenter })}
  />
);

With the useRive hook:

import { useRive, Layout, Fit, Alignment } from '@rive-app/react-canvas';

export default function Example() {
  const { RiveComponent } = useRive({
    src: 'my-file.riv',
    artboard: 'my-artboard',
    animations: 'my-animation',
    layout: new Layout({
      fit: Fit.Cover,
      alignment: Alignment.TopCenter,
    }),
    autoplay: true,
  });

  return <RiveComponent />;
}

New Runtime (Recommended)
Legacy Runtime

Set layout attributes for Fit and Alignment on the RiveView component directly. See Fit and Alignment for all enum options.

import {
  Alignment,
  Fit,
  RiveView,
  useRiveFile,
} from '@rive-app/react-native';

export default function LayoutExample() {
  const { riveFile } = useRiveFile(
    require('path/to/file.riv')
  );

  return (
    <View style={styles.container}>
      {riveFile ? (
        <RiveView
          file={riveFile}
          style={styles.rive}
          fit={Fit.Contain}
          alignment={Alignment.Center}
        />
      ) : null}
    </View>
  );
}

Set layout attributes for Fit and Alignment on the Rive component directly. See Fit and Alignment for all enum options.

import Rive, { Alignment, Fit } from 'rive-react-native';

export default function Simple() {
  return (
    <ScrollView>
      <Rive
        fit={Fit.Cover}
        alignment={Alignment.TopCenter}
        resourceName="truck_v7"
      />
    </ScrollView>
  );
};

Pass the Fit and Alignment to the RiveWidget widget.

return RiveWidget(
  controller: controller,
  fit: Fit.contain,
  alignment: Alignment.center,
);

Alternatively, you can also the set fit and alignment properties directly on any RivePainter, such as the RiveWidgetController:

final controller = RiveWidgetController(riveFile);
controller.fit = Fit.contain;
controller.alignment = Alignment.center;

The runtime provides the following enums to set on layout parameters:

Fit
- .fill
- .contain
- .cover
- .fitWidth
- .fitHeight
- .scaleDown
- .noFit
Alignment
- .topLeft
- .topCenter
- .topRight
- .centerLeft
- .center
- .centerRight
- .bottomLeft
- .bottomCenter
- .bottomRight

SwiftUI

The following example shows how to set layout parameters and switch them at runtime:

struct SwiftLayout: View {
    @State private var fit: RiveFit = .contain
    @State private var alignment: RiveAlignment = .center

    var body: some View {
        VStack {
            RiveViewModel(fileName: "fancy_rive_file", fit: fit, alignment: alignment).view()
        }
        HStack {
            Text("Some Fit Examples")
        }
        HStack {
            Button("Fill") { fit = .fill }
            Button("Contain") { fit = .contain }
            Button("Cover") { fit = .cover }
        }
        HStack {
            Text("Some Alignment Examples")
        }
        HStack {
            Button("Top Left") { alignment = .topLeft }
            Button("Top Center") { alignment = .topCenter }
            Button("Top Right") { alignment = .topRight }
        }
    }
}

UIKit

The following example shows how to set layout parameters and switch them at runtime:

class LayoutViewController: UIViewController {
    @IBOutlet weak var riveView: RiveView!
    var viewModel = RiveViewModel(fileName: "fancy_rive_file")

    override func viewDidLoad() {
        viewModel.setView(riveView)
    }

    @IBAction func fitButtonTriggered(_ sender: UIButton) {
        setFit(name: sender.currentTitle!)
    }

    @IBAction func alignmentButtonTriggered(_ sender: UIButton) {
        setAlignment(name: sender.currentTitle!)
    }

    func setFit(name: String) {
        var fit: RiveFit = .contain
        switch name {
        case "Fill": fit = .fill
        case "Contain": fit = .contain
        case "Cover": fit = .cover
        case "Fit Width": fit = .fitWidth
        case "Fit Height": fit = .fitHeight
        case "Scale Down": fit = .scaleDown
        case "None": fit = .noFit
        default: fit = .contain
        }
        viewModel.fit = fit
    }

    func setAlignment(name: String) {
        var alignment: RiveAlignment = .center
        switch name {
        case "Top Left": alignment = .topLeft
        case "Top Center": alignment = .topCenter
        case "Top Right": alignment = .topRight
        case "Center Left": alignment = .centerLeft
        case "Center": alignment = .center
        case "Center Right": alignment = .centerRight
        case "Bottom Left": alignment = .bottomLeft
        case "Bottom Center": alignment = .bottomCenter
        case "Bottom Right": alignment = .bottomRight
        default: alignment = .center
        }
        viewModel.alignment = alignment
    }
}

Compose
Legacy

The Fit sealed class is used to specify the fit mode. On all variants other than Layout and Fill, the Alignment enum can be supplied to specify the alignment. Note that because this is a class, it must be constructed. If an alignment is not provided, it defaults to Alignment.Center.

Rive(
    myRiveFile,
    fit = Fit.Cover(Alignment.TopCenter)
)

The Fit enum specifies the fit mode with the follow options: LAYOUT, CONTAIN, SCALE_DOWN, COVER, FIT_WIDTH, FIT_HEIGHT, FILL, and NONE.The Alignment enum specifies the alignment with the following options: TOP_LEFT, TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTER, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, and BOTTOM_RIGHT.

Using XML Layouts

The fit and alignment enum values can be applied to the riveFit and riveAlignment attributes in your XML layout:

<app.rive.runtime.kotlin.RiveAnimationView
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:riveResource="@raw/my_rive_file"
    app:riveAlignment="CENTER"
    app:riveFit="CONTAIN"
/>

Using Kotlin

The fit and alignment enum values can be applied to the fit and alignment properties on your RiveAnimationView instance:

animationView.fit = Fit.FILL
animationView.alignment = Alignment.CENTER

Responsive Layouts

Rive’s layout feature lets you design resizable artboards with built-in responsive behavior, configured from the editor. Ensure the fit mode is set to Layout at runtime and the artboard will resize to fill its container according to the constraints defined in the editor. Optionally you may provide a layout scale factor to multiply the scale of the content. This allows fine tuning the visual size within your container. This property only applies when setting the Fit mode to Layout. For more Editor information and how to configure your graphic, see Layouts Overview.

Steps

Set fit to Fit.Layout - this will automatically scale and resize the artboard to match the canvas size when calling resizeDrawingSurfaceToCanvas().
Optionally set layoutScaleFactor for manual control of the artboard size (scale factor).
Subscribe to window.onresize and call resizeDrawingSurfaceToCanvas() to adjust the artboard size as the canvas and window changes.
Subscribe to device pixel ratio changes and call resizeDrawingSurfaceToCanvas() to ensure the artboard updates correctly on various screen densities. For example, when dragging the window between multiple monitors with different device pixel ratios.

<style>
  body {
    background: #f0f0f0;
    margin: 0;
    overflow: hidden;
  }

  canvas {
    background-color: red;
    display: block;
    width: 100vw;
    height: 100vh;
  }
</style>

<canvas id="riveCanvas"></canvas>

<script src="https://unpkg.com/@rive-app/canvas@latest"></script>

<script>
  const rive = new Rive({
    src: "your-rive-file.riv",
    autoplay: true,
    canvas: riveCanvas,
    layout: new Layout({
      fit: Fit.Layout,
      // layoutScaleFactor: 2, // 2x scale of the layout, when using `Fit.Layout`. This allows you to resize the layout as needed.
    }),
    stateMachines: ["State Machine 1"],
    onLoad: () => {
      computeSize();
    },
  });

  function computeSize() {
    rive.resizeDrawingSurfaceToCanvas();
  }

  // Subscribe to window size changes and update call `resizeDrawingSurfaceToCanvas`
  window.onresize = computeSize;

  // Subscribe to devicePixelRatio changes and call `resizeDrawingSurfaceToCanvas`
  window
    .matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`)
    .addEventListener("change", computeSize);
</script>

Steps

Set fit to Fit.Layout in the Layout object - this will automatically scale and resize the artboard to match the canvas size.
Pass the Layout object to the layout prop in useRive.
Optionally set layoutScaleFactor in the Layout object for manual control of the artboard’s scale factor.
The React runtime automatically handles window resizing and device pixel ratio changes.

import { useRive, Layout, Fit } from "@rive-app/react-canvas";

export const RiveComponent = () => {
  const { RiveComponent } = useRive({
    src: "your-rive-file.riv",
    stateMachines: "State Machine 1",
    layout: new Layout({
      fit: Fit.Layout,
      // layoutScaleFactor: 2, // Optional: 2x scale of the layout
    }),
    autoplay: true,
  });

  return <RiveComponent />;
};

New Runtime (Recommended)
Legacy Runtime

Steps

Set fit to Fit.Layout - this will automatically scale and resize the artboard to match the view size.
Optionally set the layoutScaleFactor for manual control of the artboard size (scale factor). If not set, the graphic uses the DPI of the device for scaling.

export default function ResponsiveLayoutsExample() {
  const { riveFile, isLoading, error } = useRiveFile(
    require('path/to/file.riv')
  );
  const [scaleFactor, setScaleFactor] = useState(4.0);
  const riveRef = useRef<RiveViewRef>(null);
  const { width, height } = useWindowDimensions();

  useEffect(() => {
    riveRef.current?.playIfNeeded();
  }, [width, height]);

  const increaseScale = () => {
    setScaleFactor((prev) => prev + 0.5);
    riveRef.current?.playIfNeeded();
  };
  const decreaseScale = () => {
    setScaleFactor((prev) => Math.max(0.5, prev - 0.5));
    riveRef.current?.playIfNeeded();
  };

  return (
    <View style={styles.container}>
      {isLoading ? (
        <ActivityIndicator size="large" color="#0000ff" />
      ) : error ? (
        <Text style={styles.errorText}>{error}</Text>
      ) : riveFile ? (
        <RiveView
          hybridRef={{ f: (ref) => (riveRef.current = ref) }}
          file={riveFile}
          fit={Fit.Layout}
          layoutScaleFactor={scaleFactor}
          style={styles.rive}
          autoPlay={true}
        />
      ) : null}
      <View style={styles.controls}>
        <Text style={styles.label}>Layout Scale Factor</Text>
        <View style={styles.scaleControls}>
          <Button title="-" onPress={decreaseScale} />
          <View style={styles.scaleText}>
            <Text>{scaleFactor.toFixed(1)}x</Text>
          </View>
          <Button title="+" onPress={increaseScale} />
        </View>
      </View>
    </View>
  );
}

The call to playIfNeeded() ensures that the graphic is visually updated after the change. In the future this will be handled automatically.

Examples

Layout React Native Example

Steps

Set fit to Fit.Layout - this will automatically scale and resize the artboard to match the canvas size.
Optionally set layoutScaleFactor in the Layout object for manual control of the artboard’s scale factor.
The React Native runtime automatically handles window resizing and device pixel ratio changes.

import Rive, { Fit } from 'rive-react-native';

const resourceName = 'layout_test';

export default function ResponsiveLayout() {
  return (
    <Rive
      autoplay={true}
      fit={Fit.Layout}
      layoutScaleFactor={0.5} // If you do not set this (or set equal to "-1.0"), Rive will automatically scale the layout to match the device pixel ratio
      resourceName={resourceName}
      artboardName={'Artboard'}
      stateMachineName={'State Machine 1'}
    />
  );
}

Pass the Fit.layout to the RiveWidget widget. This will automatically scale and resize the artboard to match the widget size. You can also set the layoutScaleFactor to control the scale of the artboard. This is useful for adjusting the size of the artboard when using Fit.layout.

return RiveWidget(
  controller: controller,
  fit: Fit.layout,
  layoutScaleFactor: 2.0, // Optional: 2x scale of the layout,
);

Alternatively, you can also set the fit and layoutScaleFactor properties directly on any RivePainter, such as the RiveWidgetController:

final controller = RiveWidgetController(riveFile);
controller.fit = Fit.layout;
controller.layoutScaleFactor = 2.0; // Optional: 2x scale of the layout

Examples

SwiftUI

Steps

Set fit on an instance of RiveViewModel to layout
Optionally set layoutScaleFactor on RiveViewModel for manual control of an artboard’s scale factor.

To enable automatically determining the scale factor, set .layoutScaleFactor to RiveViewModel.layoutScaleFactorAutomatic. This is the default value; it is equivalent to -1. When set, Rive will listen for window and screen changes for the view model’s view, and automatically apply the correct scale factor for the current view hierarchy.

let viewModel = RiveViewModel(fileName: "...")
viewModel.fit = .layout
viewModel.layoutScaleFactor = RiveViewModel.layoutScaleFactorAutomatic // Allow Rive to determine the scale factor
viewModel.layoutScaleFactor = 2.0 // Or, explicitly set the scale factor

Compose
Legacy

See also the Compose Layout sample.Set the fit parameter to Fit.Layout in the Rive composable. This will resize the artboard to match the container size. The Fit.Layout constructor takes an optional layoutScaleFactor parameter to adjust the scale of the artboard. By default it is 1, i.e. no scaling.

Rive(
    myRiveFile,
    fit = Fit.Layout(1.2f) // 1.2x scale
)

Sample

See the Layout sample.

Using XML Layouts

Set the riveFit attribute to "LAYOUT".

<app.rive.runtime.kotlin.RiveAnimationView
    ...
    app:riveFit="LAYOUT"
/>

Using Kotlin

Set the RiveAnimationView’s fit property to LAYOUT.

val animationView = findViewById<RiveAnimationView>(R.id.my_view)
animationView.fit = Fit.LAYOUT

Adjusting the Layout Scale Factor

To adjust the scale factor of the contents, use the layoutScaleFactor property. This is nullable, so by default, it will use the density as reported by resources.displayMetrics.density. You can override this to any positive float value, or return control to the system by resetting to null:

// Force a set scale factor
animationView.layoutScaleFactor = 2.5f
// Reset to system control
animationView.layoutScaleFactor = null

Resizing the Artboard

The artboard size can be manually controlled by using the width and height properties. resetArtboardSize() can be used to return these values to their defaults.

// Force a certain artboard size
animationView.controller.activeArtboard?.width = 1000f
animationView.controller.activeArtboard?.height = 1000f
// Reset the artboard size to defaults
animationView.controller.activeArtboard?.resetArtboardSize()

Runtime Fundamentals

App Runtimes

The Fit Mode

Alignment

Bounds

Applying the Fit Mode

SwiftUI

UIKit

Using XML Layouts

Using Kotlin

Responsive Layouts

Sample

Using XML Layouts

Using Kotlin

Adjusting the Layout Scale Factor

Resizing the Artboard

Runtime Fundamentals

App Runtimes

​The Fit Mode

​Alignment

​Bounds

​Applying the Fit Mode

​SwiftUI

​UIKit

​Using XML Layouts

​Using Kotlin

​Responsive Layouts

​Sample

​Using XML Layouts

​Using Kotlin

​Adjusting the Layout Scale Factor

​Resizing the Artboard

The Fit Mode

Alignment

Bounds

Applying the Fit Mode

SwiftUI

UIKit

Using XML Layouts

Using Kotlin

Responsive Layouts

Sample

Using XML Layouts

Using Kotlin

Adjusting the Layout Scale Factor

Resizing the Artboard