> ## Documentation Index
> Fetch the complete documentation index at: https://rive.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Binding

> Connect your code to bound editor elements using View Models

export const Apple = {
  currentRuntimeName: "New Runtime",
  legacyRuntimeName: "Legacy Runtime"
};

export const Demos = ({examples, runtime, columns = 2, children, childrenIndex = 0, learnByExample = false}) => {
  const examplesData = {
    ikConstraint: {
      title: 'IK Constraints',
      description: 'Check out this example to see IK constraints in action.',
      image: "https://static.rive.app/docs/ik-constraint.gif",
      stateMachines: "State Machine 1",
      links: {
        editor: "https://rive.app/community/files/28080-53039-ik-constraint/"
      }
    },
    cachingARiveFile: {
      title: 'Caching a Rive File',
      description: 'Load the .riv into memory once, use it multiple times.',
      riv: 'https://static.rive.app/rivs/rives_animated_emojis.riv',
      stateMachines: "State Machine 1",
      artboard: "Emoji_package",
      links: {
        web: "https://codesandbox.io/p/sandbox/rive-js-caching-a-rive-file-g675my?file=%2Fsrc%2Findex.ts%3A9%2C1",
        react: "https://codesandbox.io/p/sandbox/rive-react-caching-a-rive-file-53gmdf?file=%2Fsrc%2FApp.tsx"
      },
      source: ["https://rive.app/marketplace/24644-46045-caching-a-rive-file-at-runtime/"]
    },
    dataBindingArtboards: {
      title: 'Data Binding Artboards',
      description: 'Swap an artboard with another artboard from the same .riv or one loaded at runtime.',
      image: '/images/runtimes/rive-data-bind-components.webp',
      links: {
        web: 'https://codesandbox.io/p/sandbox/rive-js-data-binding-artboards-jx3pf9?file=%2Fsrc%2Findex.mjs%3A5%2C19',
        react: 'https://codesandbox.io/p/sandbox/rive-react-data-binding-artboards-kmvzh8?file=%2Fsrc%2FApp.tsx',
        flutter: 'https://github.com/rive-app/rive-flutter/blob/master/example/lib/examples/databinding_artboards.dart',
        reactNative: 'https://github.com/rive-app/rive-nitro-react-native/blob/main/example/src/demos/DataBindingArtboardsExample.tsx',
        android: "https://github.com/rive-app/rive-android/blob/master/app/src/main/java/app/rive/runtime/example/ComposeArtboardBindingActivity.kt"
      },
      source: ["https://rive.app/marketplace/24641-46042-data-binding-artboards/", "https://rive.app/marketplace/24642-47536-data-binding-artboards/"]
    },
    dataBindingImages: {
      title: 'Data Binding Images',
      description: 'Replace images at runtime using data binding images with javascript.',
      image: '/images/runtimes/rive-db-images.webp',
      links: {
        web: 'https://codesandbox.io/p/sandbox/objective-cohen-sqwh9q?file=%2Fsrc%2Findex.ts',
        flutter: 'https://github.com/rive-app/rive-flutter/blob/master/example/lib/examples/databinding_images.dart',
        android: "https://github.com/rive-app/rive-android/blob/master/app/src/main/java/app/rive/runtime/example/ComposeImageBindingActivity.kt"
      },
      source: ["https://rive.app/marketplace/25472-47537-data-binding-images/"]
    },
    dataBindingLists: {
      title: 'Data Binding Lists',
      description: 'Add, remove, edit, and swap items in your data binding list.',
      image: '/images/runtimes/rive-db-lists.webp',
      links: {
        web: 'https://codesandbox.io/p/sandbox/suspicious-hertz-2lg4m8?file=%2Fsrc%2Findex.ts',
        react: 'https://codesandbox.io/p/sandbox/rive-react-data-binding-lists-4msh9z?file=%2Fsrc%2FApp.tsx',
        flutter: 'https://github.com/rive-app/rive-flutter/blob/master/example/lib/examples/databinding_lists.dart',
        android: "https://github.com/rive-app/rive-android/blob/master/app/src/main/java/app/rive/runtime/example/ComposeListActivity.kt"
      },
      source: ["https://rive.app/marketplace/25474-47539-data-binding-lists/"]
    },
    dataBindingQuickStart: {
      title: "Data Binding",
      description: "Get started with Data Binding at runtime.",
      image: "/images/runtimes/rewards.gif",
      links: {
        flutter: "https://github.com/rive-app/rive-flutter/blob/master/example/lib/examples/databinding.dart",
        reactNative: "https://github.com/rive-app/rive-react-native/blob/main/example/app/(examples)/DataBinding.tsx",
        unity: "https://github.com/rive-app/rive-unity-examples/blob/main/getting-started/Assets/RewardsController.cs",
        apple: "https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/SwiftUI/RewardsView.swift",
        android: "https://github.com/rive-app/rive-android/blob/master/app/src/main/java/app/rive/runtime/example/ComposeDataBindingActivity.kt"
      },
      source: ["https://rive.app/marketplace/25475-47540-data-binding-demo/"]
    },
    dataBindingSolos: {
      title: "Data Binding Solos",
      description: "Control solos at runtime using strings, numbers, or enums.",
      image: '/images/runtimes/data-binding-solos.gif',
      links: {
        react: "https://codesandbox.io/p/sandbox/rive-react-controlling-solos-at-runtime-ctcnlx?file=%2Fsrc%2FApp.tsx"
      },
      source: ["https://rive.app/marketplace/24643-46044-data-binding-solos/"]
    },
    googleAppAds: {
      title: "Google App Ads",
      description: "How to make an interactive Google App with Rive.",
      image: "/images/runtimes/google-app-ads.png",
      links: {
        mobile: "https://github.com/rive-app/rive-use-cases/tree/main/rive-google-ads"
      }
    },
    layouts: {
      title: "Responsive Layouts",
      description: "Create responsive layouts that adapt to different screen sizes.",
      riv: "https://static.rive.app/rivs/layouts_demo.riv",
      stateMachines: "State Machine 1",
      artboard: "Demo",
      links: {
        web: "https://codesandbox.io/p/devbox/rive-responsive-layout-js-forked-m77nlw",
        react: "https://codesandbox.io/p/devbox/rive-responsive-layouts-react-forked-nmpv39?file=%2Fsrc%2FApp.tsx",
        flutter: "https://github.com/rive-app/rive-flutter/blob/master/example/lib/examples/responsive_layouts.dart",
        reactNative: "https://github.com/rive-app/rive-react-native/blob/main/example/app/(examples)/ResponsiveLayout.tsx",
        android: "https://github.com/rive-app/rive-android/blob/master/app/src/main/java/app/rive/runtime/example/ComposeLayoutActivity.kt"
      },
      source: ["https://rive.app/marketplace/24638-46038-layouts-demo/"]
    },
    fontsHostedCompressed: {
      title: 'Load a Compressed Font for Web',
      description: 'Dynamically load a font asset from a hosted location with compression.',
      image: '/images/runtimes/brotli-compressed-fonts.webp',
      links: {
        react: 'https://codesandbox.io/p/sandbox/prod-sound-6yc5xl?file=%2Fsrc%2FApp.tsx%3A19%2C1'
      },
      source: ["https://rive.app/marketplace/25473-47538-loading-compressed-fonts-web/"]
    },
    quickStart: {
      title: "Data Binding Quick Start",
      image: '/images/runtimes/quick-start.gif',
      description: 'Load and control your Rive (.riv) file.',
      links: {
        web: 'https://codesandbox.io/p/sandbox/rive-quick-start-js-xmwcm6?file=%2Fsrc%2Findex.ts',
        react: 'https://codesandbox.io/p/sandbox/rive-react-quick-start-4xy76h?file=%2Fsrc%2FApp.tsx%3A77%2C14',
        reactJs: 'https://codesandbox.io/p/devbox/rive-react-vanilla-js-quick-start-kz66t4?file=%2Fsrc%2FApp.tsx%3A53%2C7',
        reactNative: 'https://github.com/rive-app/rive-nitro-react-native/blob/main/example/src/demos/QuickStart.tsx',
        unity: '/game-runtimes/unity/tutorials/health-bar'
      },
      source: ["https://rive.app/marketplace/24637-46037-health-bar-data-binding-quick-start/"]
    },
    quickStartReact: {
      title: "Data Binding Quick Start",
      image: '/images/runtimes/quick-start.gif',
      description: 'Load and control your Rive (.riv) file.',
      links: {
        react: 'https://codesandbox.io/p/sandbox/rive-react-quick-start-4xy76h?file=%2Fsrc%2FApp.tsx%3A77%2C14',
        reactJs: 'https://codesandbox.io/p/devbox/rive-react-vanilla-js-quick-start-kz66t4?file=%2Fsrc%2FApp.tsx%3A53%2C7'
      },
      source: ["https://rive.app/marketplace/24637-46037-health-bar-data-binding-quick-start/"]
    },
    scriptingDrawingShapes: {
      title: "Drawing with Scripting",
      image: "https://static.rive.app/docs/drawing-demo.png",
      description: "Draw a squirkle, a star, and an animated wave with scripting.",
      links: {
        editor: "https://rive.app/community/files/25751-48087-drawing-shapes-with-scripting"
      }
    },
    scriptingMasonry: {
      title: "Masonry Layout",
      image: "https://static.rive.app/docs/masonry.png",
      description: "Create a masonry layout using a Layout script.",
      links: {
        editor: "https://rive.app/community/files/25826-masonry-layout/"
      }
    },
    scriptingParticleEmitter: {
      title: "Particle Emitter",
      riv: "https://static.rive.app/rivs/particle-demo.riv",
      artboard: "Demo",
      description: "A small, self contained particle system for Rive node and layout scripts.",
      links: {
        editor: "https://rive.app/community/files/28062-53012-particle-librar/"
      }
    },
    scriptingTippingConverter: {
      title: "Custom Converter",
      image: "https://static.rive.app/docs/tipping-scripting-converter.gif",
      description: "Calculate the bill total using the converter's input value added to data binding values.",
      links: {
        editor: "https://uat.rive.app/community/files/610-1126-custom-converter-with-scripting"
      }
    },
    scriptingUnitTesting: {
      title: "Unit Testing",
      image: "https://static.rive.app/docs/scripting-default-thumb.png",
      description: "This hands-on example demonstrates unit testing rgbToHex and hexToRgb color utilities.",
      links: {
        editor: "https://rive.app/community/files/25752-48088-test-script"
      }
    },
    scriptingSnakeGame: {
      title: "Snake - Complete Game",
      image: "https://static.rive.app/docs/snake-game.png",
      description: "Check out this complete game built entirely with Rive using scripting.",
      links: {
        editor: "https://rive.app/community/files/25748-48110-snake-game/"
      }
    },
    scriptingMultiTouch: {
      title: "Tracking Multi-touch",
      image: "https://static.rive.app/docs/scripting-default-thumb.png",
      description: "Keep track of every finger.",
      links: {
        editor: "https://rive.app/community/files/25754-48090-multi-touch-with-scripting"
      }
    },
    scriptingNestedPointers: {
      title: "Nested Pointer Events",
      image: "https://static.rive.app/docs/scripting-default-thumb.png",
      description: "Pass pointer events from the parent component to the instantiated children.",
      links: {
        editor: "https://rive.app/community/files/25750-48086-scripting-nested-pointer-events/"
      }
    },
    scriptingBoilPathEffect: {
      title: "Boiling Path Effect",
      image: "https://static.rive.app/docs/boiling-effect.gif",
      description: "Apply a boiling effect to any path using scripting.",
      links: {
        editor: "https://rive.app/community/files/25767-48113-scripting-path-effect-boil"
      }
    },
    scriptingTextPathEffect: {
      title: "Text Path Effect",
      image: "https://static.rive.app/docs/text-path-effect.gif",
      description: "Control a text path using scripting.",
      links: {
        editor: "https://rive.app/community/files/25823-text-path-effects/"
      }
    },
    scriptingDrawImages: {
      title: "Render an Image with Scripting",
      image: "https://static.rive.app/docs/render-image-with-scripting.jpg",
      description: "Draw an image, give it transforms, control its mesh, and add clipping all through scripting.",
      links: {
        editor: "https://rive.app/community/files/26406-draw-an-image-with-scripting"
      }
    },
    scriptingSlotMachine: {
      title: "Slot Machine - Complete Game",
      image: "https://static.rive.app/docs/slot-machine.png",
      description: "Build a complete casino game using scripting.",
      links: {
        editor: "https://rive.app/community/files/25759-slot-machine-game-with-scripting/"
      }
    },
    scriptingLists: {
      title: "Scripting Lists",
      image: "/images/runtimes/rive-db-lists.webp",
      description: "Add, remove, edit, and swap items in your data binding list using Rive scripting.",
      links: {
        editor: "https://rive.app/community/files/27098-51051-scripting-lists"
      }
    },
    scriptingPlinko: {
      title: "Plinko - Complete Game",
      image: "https://static.rive.app/docs/scripting-plinko-game.png",
      description: "Build a complete Plinko game using Layout, Node, and Path Effect scripts.",
      links: {
        editor: "https://rive.app/marketplace/25772-blinko-scripted-game/"
      }
    },
    constraints: {
      title: "Constraints",
      image: "https://static.rive.app/docs/constraints.gif",
      description: "Transform, Translate, Scale, and Rotation Constraints.",
      links: {
        editor: "https://rive.app/community/files/28081-53040-constraints/"
      }
    }
  };
  const runtimesInOrder = ['web', 'react', 'reactJs', 'reactNative', 'flutter', 'apple', 'android', 'unity', 'unreal', 'mobile', 'editor'];
  const runtimeTitles = {
    web: 'Web',
    reactJs: 'React (Imperative)',
    react: 'React',
    reactNative: "React Native",
    flutter: 'Flutter',
    apple: 'Apple',
    android: 'Android',
    unity: 'Unity',
    unreal: 'Unreal',
    mobile: 'Mobile',
    editor: 'Try in Rive'
  };
  const riveInstances = useRef([]);
  const initRives = () => {
    const rive = window.rive;
    examples.forEach(example => {
      const {riv, stateMachines = "State Machine 1", artboard} = examplesData[example];
      if (riv) {
        const canvasId = `rive-canvas-${example}`;
        const canvas = document.getElementById(canvasId);
        if (canvas) {
          const r = new rive.Rive({
            src: riv,
            stateMachines,
            canvas,
            artboard,
            autoBind: true,
            autoplay: true,
            Layout: new rive.Layout({
              fit: rive.Fit.Layout
            }),
            onLoad: () => {
              r.resizeDrawingSurfaceToCanvas();
              riveInstances.current.push(r);
            }
          });
        }
      }
    });
  };
  useEffect(() => {
    if (window.rive) {
      initRives();
      return;
    }
    const checkRive = () => {
      if (window.rive) {
        initRives();
        window.removeEventListener("rive-loaded", checkRive);
      }
    };
    const handleResize = () => {
      riveInstances.current.forEach(instance => {
        instance.resizeDrawingSurfaceToCanvas();
      });
    };
    window.addEventListener("rive-loaded", checkRive);
    window.addEventListener("resize", handleResize);
    return () => {
      window.removeEventListener("rive-loaded", checkRive);
      window.removeEventListener("resize", handleResize);
      riveInstances.current.forEach(instance => {
        instance.cleanup();
      });
    };
  }, []);
  const RuntimeLink = ({link, runtime}) => {
    if (!link) return null;
    if (runtime === 'editor') {
      link = `${link}?utm_source=docs&utm_medium=docs_demo_card`;
    }
    return <a href={link} target="_blank" className="cursor-pointer border border-neutral-600 hover:border-white rounded-[4px] text-14 py-1 px-5 mr-[10px] mb-[10px]">
        {runtimeTitles[runtime]}
      </a>;
  };
  const CardContainer = ({children: content}) => {
    return <div className="flex flex-col card block font-normal group relative my-2 ring-2 ring-transparent rounded-2xl bg-white dark:bg-background-dark border border-gray-950/10 dark:border-white/10 overflow-hidden w-full">
        {content}
      </div>;
  };
  const getSrc = imageSrc => {
    if (location.hostname === "localhost" && imageSrc.startsWith("/images/")) {
      return imageSrc;
    } else if (imageSrc.startsWith('https:')) {
      return imageSrc;
    }
    return `https://rive.app/docs${imageSrc}`;
  };
  return <div className={`
        card-group not-prose grid gap-x-4
        grid-cols-1
        ${columns >= 2 && "md:grid-cols-2"}
        ${columns >= 3 && "xl:grid-cols-3 xl:w-[67rem] xl:max-w-[calc(100vw-25rem)]"}
      `}>
      {examples.map((example, index) => {
    const {title, image, links, description, source, riv} = examplesData[example];
    const canvasId = `rive-canvas-${example}`;
    return <>
            {index === childrenIndex && children}
            <CardContainer key={canvasId}>
              <div className="w-full h-0 relative pb-[75%]">
                <div className="absolute inset-0">
                  {image && <img alt={title} className="w-full object-cover object-center" src={getSrc(image)} />}

                  {riv && !image && <canvas id={canvasId} style={{
      width: "100%",
      height: "100%"
    }} />}
                </div>
              </div>
              <div className="flex flex-grow flex-col px-6 py-5 relative" data-component-part="card-content-container">
                <div className="flex flex-col grow">
                  <h2 className="not-prose font-semibold text-base text-gray-800 dark:text-white" data-component-part="card-title">{learnByExample ? "Learn by Example" : title}</h2>

                  <div className="flex flex-col grow prose mt-1 font-normal text-sm leading-6 text-gray-600 dark:text-gray-400" data-component-part="card-content">
                    <div className="grow flex flex-col">
                      {description && !learnByExample && <p>{description}</p>}
                      {source && source.length > 0 && <p className="mt-3">
                            {source.map((item, index) => {
      if (source.length == 1) {
        return <>Open the <a href={item}>Rive file</a>.</>;
      }
      if (index == 0) {
        return <>Open <a href={item}>Rive file 1</a></>;
      }
      return <>, <a href={item}>file {index + 1}</a></>;
    })}
                          </p>}
                    </div>
                    {<div className="mt-6 flex flex-wrap">
                        {runtimesInOrder.map(currentRuntime => {
      if (runtime && currentRuntime !== runtime) return;
      return <RuntimeLink key={currentRuntime} runtime={currentRuntime} link={links[currentRuntime]} />;
    })}
                      </div>}
                  </div>
                </div>
              </div>
            </CardContainer>
          </>;
  })}
    </div>;
};

export const YouTube = ({id, timestamp}) => {
  const videoSrc = timestamp ? `https://www.youtube.com/embed/${id}?start=${timestamp}` : `https://www.youtube.com/embed/${id}`;
  return <iframe width="100%" height="400" src={videoSrc} title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />;
};

Before engaging with the runtime data binding APIs, it is important to familiarize yourself with the core concepts presented in the [Overview](/editor/data-binding/overview).

<Demos examples={["dataBindingQuickStart"]} runtime="apple" />

# View Models

View models describe a set of properties, but cannot themselves be used to get or set values - that is the role of [view model instances](#view-model-instances).

To begin, we need to get a reference to a particular view model. This can be done either by index, by name, or the default for a given artboard, and is done from the Rive file. The default option refers to the view model assigned to an artboard by the dropdown in the editor.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    View models are not their own type; rather, they are a source when creating a view model instance from a `File`.

    You can define the source of a view model via the `ViewModelSource` type.

    ```swift theme={null}
    case artboardDefault(Artboard) // References the default view model for an Artboard
    case name(String) // References a view model from a file by name
    ```

    These sources are used in conjunction with getting a view model instance. See [View Model Instances](#view-model-instances) for more information.
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)
    let file = riveViewModel.riveModel!.riveFile

    // Data binding view model by name
    let viewModelByName = file.viewModelNamed("...")

    // Data binding view model by index
    for index in 0..<file.viewModelCount {
        let viewModelByIndex = file.viewModel(at: index)
    }

    // Default data binding view model for an artboard
    let artboard = riveViewModel.riveModel!.artboard
    let viewModelForArtboard = file.viewModel(for: artboard)
    ```
  </Tab>
</Tabs>

# View Model Instances

Once we have a reference to a view model, it can be used to create an instance. When creating an instance, you have four options:

1. Create a blank instance - Fill the properties of the created instance with default values as follows:

   | Type              | Value           |
   | ----------------- | --------------- |
   | Number            | 0               |
   | String            | Empty string    |
   | Boolean           | False           |
   | Color             | 0xFF000000      |
   | Trigger           | Untriggered     |
   | Enum              | The first value |
   | Image             | No image        |
   | Artboard          | No artboard     |
   | List              | Empty list      |
   | Nested view model | Null            |

2. Create the default instance - Use the instance labelled "Default" in the editor. Usually this is the one a designer intends as the primary one to be used at runtime.

3. Create by index - Using the order returned when iterating over all available instances. Useful when creating multiple instances by iteration.

4. Create by name - Use the editor's instance name. Useful when creating a specific instance.

<Note>
  In some samples, due to the wordiness of "view model instance", we use the abbreviation "VMI", as well as "VM" for "view model".
</Note>

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    The following section assumes that you have read through the [Apple](/runtimes/apple/apple) overview.

    ```swift theme={null}
    // From a file
    let file: File = ...

    // When using a view model by name:
    // A blank view model instance
    var blankInstance = try await file.createViewModelInstance(.blank(from: .name("ViewModel")))
    // The default instance for the view model
    var defaultInstance = try await file.createViewModelInstance(.viewModelDefault(from: .name("ViewModel")))
    // An instance by name from the view model
    var namedInstance = try await file.createViewModelInstance(.name("Instance", from: .name("ViewModel")))

    // Alternatively, using the default view model for an artboard
    let artboard: Artboard = ...
    // A blank view model instance
    blankInstance = try await file.createViewModelInstance(.blank(from: .artboardDefault(Artboard)))
    // The default instance for the view model
    defaultInstance = try await file.createViewModelInstance(.viewModelDefault(from: .artboardDefault(Artboard)))
    // An instance by name from the view model
    namedInstance = try await file.createViewModelInstance(.name("Instance", from: .artboardDefault(Artboard)))
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)
    let viewModel = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!

    // Create blank
    let blankInstance = viewModel.createInstance()

    // Create default
    let defaultInstance = viewModel.createDefaultInstance()

    // Create by index
    for index in 0..<viewModel.instanceCount {
        let instanceByIndex = viewModel.createInstance(fromIndex: index)
    }

    // Create by name
    for name in viewModel.instanceNames {
        let instanceByName = viewModel.createInstance(fromName: name)
    }
    ```
  </Tab>
</Tabs>

### Binding

The created instance can then be assigned to a state machine or artboard. This establishes the bindings set up at edit time.

It is preferred to assign to a state machine, as this will automatically apply the instance to the artboard as well. Only assign to an artboard if you are not using a state machine, i.e. your file is static or uses linear animations.

<Note>
  The initial values of the instance are not applied to their bound elements until the state machine or artboard advances.
</Note>

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    Given the following example code:

    ```swift theme={null}
    let file: File = ...
    let artboard: Artboard = try await file.createArtboard()
    let stateMachine: StateMachine = try await artboard.createStateMachine()
    let viewModelInstance = try await file.createViewModelInstance(...)
    ```

    You can manually bind the view model instance to the state machine:

    ```swift theme={null}
    stateMachine.bindViewModelInstance(viewModelInstance)
    ```

    Alternatively, you can utilize the `Rive` type to (automatically) data bind a view model instance:

    ```swift theme={null}
    // Automatically find a default view model instance to bind. This is the default value, if you do not pass in a dataBind argument.
    var rive = try await Rive(file: file, artboard: artboard, stateMachine: stateMachine, dataBind: .auto)
    // Bind a view model instance
    var rive = try await Rive(file: file, artboard: artboard, stateMachine: stateMachine, dataBind: .viewModelInstance(viewModelInstance))
    // Do not bind. This assumes you have manually bound a view model instance earlier
    var rive = try await Rive(file: file, artboard: artboard, stateMachine: stateMachine, dataBind: .none)
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)
    let artboard = riveViewModel.riveModel!.artboard,
    let instance = riveViewModel.riveModel!.riveFile.defaultViewModel(for: artboard).createDefaultInstance()!

    // Apply the instance to the state machine (preferred)
    // Applying to a state machine will automatically bind to its artboard
    riveViewModel.riveModel!.stateMachine.bind(instance)

    // Alternatively, apply the instance to the artboard
    artboard.bind(viewModelInstance: instance)
    ```
  </Tab>
</Tabs>

### Auto-Binding

Alternatively, you may prefer to use auto-binding. This will automatically bind the default view model of the artboard using the default instance to both the state machine and the artboard. The default view model is the one selected on the artboard in the editor dropdown. The default instance is the one marked "Default" in the editor.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    Given the following example code:

    ```swift theme={null}
    let file: File = ...
    let artboard: Artboard = try await file.createArtboard()
    let stateMachine: StateMachine = try await artboard.createStateMachine()
    let viewModelInstance = try await file.createViewModelInstance(...)
    ```

    When creating a `Rive` object, you can elect to auto bind:

    ```swift theme={null}
    // Automatically find a default view model instance to bind. This is the default value, if you do not pass in a dataBind argument.
    var rive = try await Rive(file: file, artboard: artboard, stateMachine: stateMachine, dataBind: .auto)
    // or
    var rive = try await Rive(file: file, artboard: artboard, stateMachine: stateMachine)
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)
    riveViewModel.riveModel?.enableAutoBind { instance in
        // Store a reference to `instance` to later access properties
        // The instance may change as state machines and artboards change
    }

    // If you'd like to disable autoBind after enabling…
    riveViewModel.riveModel!.disableAutoBind()
    ```
  </Tab>
</Tabs>

# Properties

A property is a value that can be read, set, or observed on a view model instance. Properties can be of the following types:

| Type                   | Supported |
| ---------------------- | --------- |
| Floating point numbers | ✅         |
| Booleans               | ✅         |
| Triggers               | ✅         |
| Strings                | ✅         |
| Enumerations           | ✅         |
| Colors                 | ✅         |
| Nested View Models     | ✅         |
| Lists                  | ✅         |
| Images                 | ✅         |
| Artboards              | ✅         |

For more information on version compatibility, see the [Feature Support](/feature-support) page.

### Listing Properties

Property descriptors can be inspected on a view model to discover at runtime which are available. These are not the mutable properties themselves though - once again those are on instances. These descriptors have a type and name.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    ```swift theme={null}
    let file: File = ...
    let properties = try await file.getProperties(of: "ViewModel")
    for property in properties {
        print(property.type) // enum of string, number, boolean, etc
        print(property.name) // The name of the property within the view model
        print(property.metaData) // Additional metadata for the property, if available
    }
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)
    let viewModel = riveViewModel.riveModel!.file.viewModelNamed(...)!
    for property in viewModel.properties {
        print(property.type) // String, number, boolean, etc
        print(property.name) // The name of the property within the view model
    }
    ```
  </Tab>
</Tabs>

### Reading and Writing Properties

References to these properties can be retrieved by name or path.

Some properties are mutable and have getters, setters, and observer operations for their values. Getting or observing the value will retrieve the latest value set on that property's binding, as of the last state machine or artboard advance. Setting the value will update the value and all of its bound elements.

<Note>
  After setting a property's value, the changes will not apply to their bound elements until the state machine or artboard advances.
</Note>

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    Property types are a very thin wrapper around the path and return type of a property.

    All property APIs (e.g setters, getters, and triggers) are available as part of a `ViewModelInstance` object.

    <CodeGroup>
      ```swift String theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      // String
      let stringProperty = StringProperty(path: "path/to/string")
      let stringValue = try await viewModelInstance.value(of: stringProperty)
      viewModelInstance.setValue(of: stringProperty, to: "value")
      ```

      ```swift Number theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      let numberProperty = NumberProperty(path: "path/to/number")
      let numberValue = try await viewModelInstance.value(of: numberProperty)
      viewModelInstance.setValue(of: numberValue, to: 9001)
      ```

      ```swift Bool theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      let boolProperty = BoolProperty(path: "path/to/bool")
      let boolValue = try await viewModelInstance.value(of: boolProperty)
      viewModelInstance.setValue(of: boolProperty, to: true)
      ```

      ```swift Color theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      let colorProperty = ColorProperty(path: "path/to/color")
      let colorValue = try await viewModelInstance.value(of: colorProperty)
      viewModelInstance.setValue(of: colorProperty, to: Color(red: 255, green: 255, blue: 255, alpha: 255))
      ```

      ```swift Enum theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      let enumProperty = EnumProperty(path: "path/to/enum")
      let enumValue = try await viewModelInstance.value(of: enumProperty)
      viewModelInstance.setValue(of: enumProperty, to: "value")
      ```

      ```swift Trigger theme={null}
      let file: File = ...
      let viewModelInstance = try await file.createViweModelInstance(...)

      let triggerProperty = TriggerProperty(path: "path/to/trigger")
      viewModelInstance.fire(trigger: triggerProperty)
      ```
    </CodeGroup>
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)

    var viewModelInstance: RiveDataBindingViewModel.Instance!

    // You can get the view model instance when enabling auto binding
    riveViewModel.riveModel?.enableAutoBind { instance in
        // Store a reference to instance
        viewModelInstance = instance
    }

    // Alternatively, you can create a view model instance manually
    viewModelInstance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

    // Strings
    let stringProperty = instance.stringProperty(fromPath: "...")!
    // Updating its value
    stringProperty.value = "Hello, Rive"
    // Get its value
    print(stringProperty.value)

    // You can also set and get values without storing a strong reference
    instance.stringProperty(fromPath: "...").value = "Hello again, Rive"

    // Numbers
    let numberProperty = instance.numberProperty(fromPath: "...")!
    // Updating its value
    numberProperty.value = 1337
    // Get its value
    print(numberProperty.value)

    // You can also set and get values without storing a strong reference
    instance.numberProperty(fromPath: "...").value = 1337

    // Booleans
    let booleanProperty = instance.booleanProperty(fromPath: "...")!
    // Updating its value
    booleanProperty.value = true
    // Get its value
    print(booleanProperty.value)

    // You can also set and get values without storing a strong reference
    instance.booleanProperty(fromPath: "...").value = true

    // Colors
    let colorProperty = instance.colorProperty(fromPath: "...")!
    // Updating its value, which is a UIColor/NSColor, so all static helpers apply.
    colorProperty.value = .red
    // Get its value
    print(colorProperty.value)

    // You can also set and get values without storing a strong reference
    instance.colorProperty(fromPath: "...").value = .red

    // Enums
    let enumProperty = instance.enumProperty(fromPath: "...")!
    // Updating its value
    enumProperty.value = "Foo"
    // Get its value
    print(enumProperty.value)
    // Print all possible values
    print(enumProperty.values)

    // You can also set and get values without storing a strong reference
    instance.enumProperty(fromPath: "...").value = "Foo"

    // Trigger
    let triggerProperty = instance.triggerProperty(fromPath: "...")!
    // Fire the trigger
    triggerProperty.trigger()
    ```
  </Tab>
</Tabs>

### Nested Property Paths

View models can have properties of type view model, allowing for arbitrary nesting. You can chain property calls on each instance starting from the root until you get to the property of interest. Alternatively, you can do this through a path parameter, which is similar to a URI in that it is a forward slash delimited list of property names ending in the name of the property of interest.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    Property types are no longer reference types, and require the name or full path to a property when initializing the property value type. There is no longer an API to chain nested properties.

    See [Properties](#properties) for usage details.
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)

    var viewModelInstance: RiveDataBindingViewModel.Instance!

    // You can get the view model instance when enabling auto binding
    riveViewModel.riveModel?.enableAutoBind { instance in
        // Store a reference to instance
        viewModelInstance = instance
    }

    // Alternatively, you can create a view model instance manually
    viewModelInstance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

    let nestedNumberByChain = instance
                                .viewModelInstanceProperty(fromPath: "Nested View Model")
                                .viewModelInstanceProperty(fromPath: "Another Nested View Model")
                                .numberProperty(fromPath: "Number")

    let nestedNumberByPath = instance.numberProperty(fromPath: "Nested View Model/Another Nested View Model/Number")
    ```
  </Tab>
</Tabs>

### Observability

You can observe changes over time to property values, either by using listeners or a platform equivalent method. Once observed, you will be notified when the property changes are applied by a state machine advance, whether that is a new value that has been explicitly set or if the value was updated as a result of a binding.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    Property listeners utilize Swift Concurrency's async throwing stream API. If a property returns a value, you can listen to its changes by calling the `valueStream(of:)` method on a `ViewModelInstance` object.

    ```swift theme={null}
    let file: File = ...
    let viewModelInstance = try await file.createViewModelInstance(...)
    let stringProperty = StringProperty(path: "path/to/string")
    let valueStream = viewModelInstance.valueStream(of: stringProperty)
    do {
        for try await value in valueStream {
            print(value)
        }
    } catch let error as ViewModelInstanceError {
        // The thrown error should always be a ViewModelInstanceError type
        print(error)
    } catch {
        print(error)
    }
    ```

    For triggers, you can listen to them by calling the `stream(of:)` method on a `ViewModelInstance` object. This returns a stream of `Void` values, which can be ignored.

    ```swift theme={null}
    let file: File = ...
    let viewModelInstance = try await file.createViewModelInstance(...)
    let triggerProperty = TriggerProperty(path: "path/to/trigger")
    let triggerStream = viewModelInstance.stream(of: triggerProperty)
    do {
        for try await _ in triggerStream {
            print("Trigger fired!")
        }
    } catch let error as ViewModelInstanceError {
        // The thrown error should always be a ViewModelInstanceError type
        print(error)
    } catch {
        print(error)
    }
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)

    var viewModelInstance: RiveDataBindingViewModel.Instance!

    // You can get the view model instance when enabling auto binding
    riveViewModel.riveModel?.enableAutoBind { instance in
        // Store a reference to instance
        viewModelInstance = instance
    }

    // Alternatively, you can create a view model instance manually
    viewModelInstance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

    // Get the string property
    let stringProperty = instance.stringProperty(fromPath: "...")!

    // Add a listener
    let listener = stringProperty.addListener { newValue in
        print(newValue)
    }

    // Remove a listener, where listener is the return value of addListener
    stringProperty.removeListener(listener)

    // Trigger properties can also be listened to for when they are triggered
    instance.triggerProperty(fromPath: "...")!.addListener {
        print("Triggered!")
    }
    ```
  </Tab>
</Tabs>

### Images

Image properties let you set and replace raster images at runtime, with each instance of the image managed independently. For example, you could build an avatar creator and dynamically update features — like swapping out a hat — by setting a view model's image property.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    To set an image, you first need to decode an image from a `Worker`. This has to be the `Worker` that was used when initializing a `File`, from which you are setting the image property of a view model instance.

    ```swift theme={null}
    let worker = try await Worker()
    let file = try await File(source: ..., worker: worker)
    let viewModelInstance = file.createViewModelInstance(...)
    let imageProperty = ImageProperty(path: "path/to/image")
    let imageData: Data = ...
    let image = try await decodeImage(from: imageData)
    viewModelInstance.setValue(of: imageProperty, to: image)
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let riveViewModel = RiveViewModel(...)

    var viewModelInstance: RiveDataBindingViewModel.Instance!

    // You can get the view model instance when enabling auto binding
    riveViewModel.riveModel?.enableAutoBind { instance in
        // Store a reference to instance
        viewModelInstance = instance
    }

    // Alternatively, you can create a view model instance manually
    viewModelInstance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

    // Create a RiveRenderImage from data
    let data = Data(...)
    var image = RiveRenderImage(data: data)! // This can return nil if the data is not a valid image

    // Or, create a RiveRenderImage from a UIImage
    image = RiveRenderImage(image: UIImage(named: "my_image")!, format: .png)! // This can return nil if the image is not a valid jpg or png image

    let imageProperty = viewModelInstance.imageProperty(fromPath: "image")!

    // Once you have your data binding view model instance, you can set the image property value
    imageProperty.setValue(image)

    // You can also pass nil to clear the image
    imageProperty.setValue(nil)
    ```
  </Tab>
</Tabs>

### Lists

List properties let you manage a dynamic set of view model instances at runtime. For example, you can build a TODO app where users can add and remove tasks in a scrollable Layout.

See the [Editor section](/editor/data-binding/lists) on creating data bound lists.

A single list property can include different view model types, with each view model tied to its own Component, making it easy to populate a list with a variety of Component instances.

With list properties, you can:

* Add a new view model instance (optionally at an index)
* Remove an existing view model instance (optionally by index)
* Swap two view model instances by index
* Get the size of a list

For more information on list properties, see the [Data Binding List Property](/editor/data-binding/lists#view-model-list-property) editor documentation.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    ```swift theme={null}
    let file: File = ...
    let viewModelInstance = try await file.createViewModelInstance(...)
    let listProperty = ListProperty(path: "path/to/list")

    let size = try await viewModelInstance.size(of: listProperty)

    // Result: [newInstance]
    let newInstance = try await file.createViewModelInstance(...)
    viewModelInstance.appendInstance(newInstance, to: listProperty)

    // Result: [insertedInstance, newInstance]
    let insertedInstance = try await file.createViewModelInstance(...)
    viewModelInstance.insertInstance(instance, to: listProperty, at: 0)

    // Result: [newInstance, insertedInstance]
    viewModelInstance.swapInstance(atIndex: 0, withIndex: 1, in: listProperty)

    // Result: [newInstance]
    viewModelInstance.removeInstance(at: 1, from: listProperty)

    // Result: newInstance
    let _ = viewModelInstance.value(of: listProperty, at: 0)

    // Result: []
    viewModelInstance.removeInstance(newInstance, from: listProperty)

    // Result: 0
    let size = try await viewModelInstance.size(of: listProperty)
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    ```swift theme={null}
    let listProperty = viewModelInstance.listProperty(fromPath: "list")!

    // Create a new view model instance and add it to the end of the list
    let firstInstance = viewModel.createInstanceByName("First Instance")!
    listProperty.add(firstInstance)

    // Create a new view model instance and add it to the beginning of the list
    let secondInstance = myViewModel.createInstanceByName("Second Instance")!
    listProperty.add(secondInstance, atIndex: 0)

    // Swap the first and second instances
    listProperty.swapInstance(atIndex: 0, withInstanceAtIndex: 1)

    // Remove both instances
    listProperty.removeInstance(secondInstance)
    listProperty.removeInstance(atIndex: 0)

    // Get and print the size of the list
    print(listProperty.size) // Prints 0
    ```
  </Tab>
</Tabs>

### Artboards

Artboard properties allows you to swap out entire components at runtime. This is useful for creating modular components that can be reused across different designs or applications, for example:

* Creating a skinning system that supports a large number of variations, such as a character creator where you can swap out different body parts, clothing, and accessories.
* Creating a complex scene that is a composition of various artboards loaded from various different Rive files (drawn to a single canvas/texture/widget).
* Reducing the size (complexity) of a single Rive file by breaking it up into smaller components that can be loaded on demand and swapped in and out as needed.

<Tabs>
  <Tab title={Apple.currentRuntimeName}>
    ```swift theme={null}
    let file: File = ...
    let viewModelInstance = try await file.createViewModelInstance(...)
    let artboardProperty = ArtboardProperty(path: "path/to/artboard")
    let artboard = try await file.createArtboard(...)
    viewModelInstance.setValue(of: artboardProperty, to: artboard)
    ```
  </Tab>

  <Tab title={Apple.legacyRuntimeName}>
    Use the `artboardProperty` method on a `RiveDataBindingViewModel.Instance` object to get the artboard property.

    Then use the `setValue` method on the artboard property object to set the new artboard value.

    `setValue` accepts a `RiveBindableArtboard` object, which is a wrapper for an artboard that can be used to set the artboard property value.

    You can get a `RiveBindableArtboard` object by using the `bindableArtboard` methods on a `RiveFile` object.

    ```swift theme={null}
    let artboardProperty = instance.artboardProperty(fromPath: "Artboard")!

    let components = RiveFile(...)
    let bindableArtboard = components.bindableArtboard(at: 0)!
    let bindableArtboard2 = components.bindableArtboard(withName: "...")!

    artboardProperty.setValue(bindableArtboard)
    ```
  </Tab>
</Tabs>

### Enums

Enums properties come in two flavors: system and user-defined. In practice, you will not need to worry about the distinction, but just be aware that system enums are available in any Rive file that binds to an editor-defined enum set, representing options from the editor's dropdowns, where user-defined enums are those defined by a designer in the editor.

Enums are string typed. The Rive file contains a list of enums. Each enum in turn has a name and a list of strings.

# Examples

See the [Data Binding view](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/SwiftUI/DataBindingView.swift) in the Example app for a demo.