Cómo usar Rive en SwiftUI (iOS)

¿Cómo instalo RiveRuntime?

El runtime de Apple es el módulo RiveRuntime del repositorio rive-app/rive-ios. Se distribuye mediante Swift Package Manager y CocoaPods.

Con Swift Package Manager en Xcode: File → Add Package Dependencies, ingresa https://github.com/rive-app/rive-ios, elige una regla de versión y agrega RiveRuntime al target de tu app. Con CocoaPods, agrega el pod a tu Podfile y ejecuta pod install.

Plataformas compatibles, según la documentación de Rive:

• iOS 14.0+
• visionOS 1.0+
• tvOS 16.0+
• macOS 13.1+
• Mac Catalyst 14.0+

El runtime suma aproximadamente 1,67 MB al tamaño de descarga y unos 4,66 MB al tamaño instalado en iOS (cifras de Rive de enero de 2026). Cada archivo .riv que incluyas se suma aparte, aunque suele pesar poco.

Agrega tu archivo .riv al target de la app como cualquier otro recurso. Asegúrate de que tenga marcada la pertenencia al target (target membership); si no, el runtime no lo encontrará al iniciar.

¿Cuál es la diferencia entre el runtime de Apple nuevo y el legacy?

Rive ahora incluye dos API de Apple en el mismo paquete Swift y pod, y ambas se importan con import RiveRuntime.

La documentación de Rive es clara: la función de inputs, ya obsoleta, "solo es compatible con el runtime legacy, no con el runtime nuevo". Esto define qué API usas. Si tu .riv solo expone inputs, usa el runtime legacy. Si tiene view models, puedes usar el runtime nuevo.

Para comprobarlo, abre el archivo en el editor de Rive y busca view models en el panel de datos, cárgalo en el Rive File Inspector gratis o pregúntale a quien creó el archivo. El comando Convert Inputs to View Models del editor puede agregar view models a un archivo basado en inputs.

¿Cómo muestro un .riv en SwiftUI?

Con el runtime legacy, crea un RiveViewModel con el nombre del archivo (sin la extensión) y el nombre de la máquina de estados, mantenlo vivo con @StateObject y llama a .view() para obtener una vista de SwiftUI.

import SwiftUI
import RiveRuntime

struct CharacterView: View {
    @StateObject private var character = RiveViewModel(
        fileName: "character",
        stateMachineName: "CharacterStateMachine"
    )

    var body: some View {
        character.view()
            .frame(width: 220, height: 220)
            .accessibilityLabel("Animated character")
    }
}

Guarda el view model en @StateObject (o en un objeto padre que sea su dueño) para que no se vuelva a crear en cada redibujado. Si se recrea, la animación se reinicia y todos los inputs vuelven a sus valores iniciales.

Si varias pantallas muestran el mismo personaje, dale a cada una su propio RiveViewModel. Un view model controla una sola vista; compartirlo entre dos vistas visibles no es compatible con la API legacy.

Define el tamaño de la vista con .frame. El ajuste predeterminado mantiene la relación de aspecto del artboard dentro del frame. Si el personaje transmite información, agrega una etiqueta de accesibilidad; si es decorativo, usa .accessibilityHidden(true).

¿Cómo asigno un input numérico o disparo un trigger?

En el runtime legacy, RiveViewModel expone setInput(_:value:) para booleanos y números (Float o Double) y triggerInput(_:) para triggers.

struct UploadView: View {
    @StateObject private var character = RiveViewModel(
        fileName: "character",
        stateMachineName: "CharacterStateMachine"
    )

    var body: some View {
        VStack(spacing: 24) {
            character.view().frame(width: 220, height: 220)
            Button("Upload") { Task { await upload() } }
        }
    }

    func upload() async {
        character.setInput("mood", value: 5.0)      // loading loop
        let ok = await performUpload()
        character.triggerInput(ok ? "success" : "error")
        character.setInput("mood", value: 0.0)      // back to idle
    }
}

Como la máquina de estados se encarga de las transiciones, tu código sigue siendo simple: asigna el loop que corresponde a lo que está haciendo la app y dispara un trigger cuando ocurre algo. Nunca necesitas saber qué animación está en pantalla en ese momento.

Los nombres de los inputs distinguen mayúsculas y minúsculas y deben coincidir exactamente con el archivo. Disparar un trigger y cambiar un número al mismo tiempo no es problema si el archivo está configurado para que las reacciones puntuales terminen antes de volver al loop actual.

Recuerda que estas llamadas forman parte del sistema de inputs obsoleto y solo funcionan en el runtime legacy de Apple. Sirven para archivos existentes basados en inputs; para archivos nuevos, considera Data Binding.

¿Cómo uso Data Binding en iOS?

En el runtime nuevo de Apple, controlas un archivo a través de su instancia de view model. Describes cada propiedad por su ruta y luego asignas valores o disparas triggers en la instancia:

let mood = NumberProperty(path: "mood")
viewModelInstance.setValue(of: mood, to: 5)

let success = TriggerProperty(path: "success")
viewModelInstance.fire(trigger: success)

En el runtime nuevo, leer valores es asíncrono y usa try await. Consulta la página de Data Binding para Apple de Rive para ver cómo obtener la instancia del view model de tu archivo y cómo observar los cambios en las propiedades.

Esto solo funciona si el .riv define un view model con rutas de propiedades que coincidan. Un archivo que solo expone inputs no tiene nada a lo que estas llamadas puedan vincularse.

Los archivos de Charmotion funcionan con ambos runtimes de Apple. Con el runtime legacy, usa RiveViewModel en CharacterStateMachine con setInput("mood", value:) y triggerInput(...). Con el runtime nuevo, crea CharacterViewModelMachine vinculado al view model Character y usa NumberProperty(path: "mood") y TriggerProperty(path: "success"). El set incluye archivos de SwiftUI listos para usar en ambos casos.

¿Cómo respeto Reducir movimiento?

Los usuarios de iOS pueden activar Configuración → Accesibilidad → Movimiento → Reducir movimiento. SwiftUI expone ese ajuste mediante el valor de entorno accessibilityReduceMotion. Léelo y muestra una imagen estática en lugar de un personaje en loop.

struct AdaptiveCharacter: View {
    @Environment(\.accessibilityReduceMotion) private var reduceMotion
    @StateObject private var character = RiveViewModel(
        fileName: "character",
        stateMachineName: "CharacterStateMachine"
    )

    var body: some View {
        if reduceMotion {
            Image("character-still")
                .resizable()
                .scaledToFit()
                .frame(width: 220, height: 220)
        } else {
            character.view().frame(width: 220, height: 220)
        }
    }
}

El valor de entorno se actualiza en tiempo real, así que la vista cambia si el usuario modifica el ajuste mientras la app está abierta. Si la animación comunica un estado, como carga o éxito, mantén esa información disponible mediante texto o un anuncio de accesibilidad para que no se pierda nada al quitar el movimiento.

Agrega un personaje de Rive a una app de SwiftUI

1. Agrega el paquete. En Xcode, agrega https://github.com/rive-app/rive-ios con Swift Package Manager y vincula RiveRuntime a tu target.
2. Incluye el archivo en el bundle. Arrastra el .riv al proyecto y confirma que forma parte del target de la app.
3. Elige el runtime. Usa el RiveViewModel legacy para archivos basados en inputs; usa el runtime nuevo solo si el archivo tiene view models.
4. Muestra la vista. Crea RiveViewModel(fileName:stateMachineName:) en un @StateObject y coloca .view() con un .frame.
5. Controla los estados. Llama a setInput("mood", value: 5.0) para los loops y a triggerInput("success") para las reacciones puntuales.
6. Respeta Reducir movimiento. Lee @Environment(\.accessibilityReduceMotion) y muestra una imagen estática cuando sea true.

Preguntas frecuentes

¿Por qué setInput no hace nada en mi app de iOS?

Las causas más comunes son un nombre incorrecto de máquina de estados o de input, o usar el runtime nuevo de Apple, que no admite inputs. Revisa que los nombres coincidan exactamente en mayúsculas y espacios, confirma que creaste un RiveViewModel con stateMachineName y asegúrate de que el view model se guarde en @StateObject en lugar de recrearse.

¿Rive funciona con UIKit además de SwiftUI?

Sí. RiveRuntime admite ambos. En el runtime legacy, RiveViewModel puede crear una vista de UIKit además de una vista de SwiftUI, y las mismas llamadas setInput y triggerInput la controlan. La documentación de Rive para Apple explica la configuración de UIKit junto con la de SwiftUI, así que puedes combinar ambos en una misma app.

¿Qué versiones de iOS admite Rive?

El runtime de Rive para Apple admite iOS 14.0 y posteriores, además de visionOS 1.0+, tvOS 16.0+, macOS 13.1+ y Mac Catalyst 14.0+. Los runtimes nuevo y legacy de Apple se distribuyen en el mismo paquete de Swift, así que las versiones mínimas aplican a cualquiera de las dos API.

¿Puedo usar un archivo de Rive en un widget o en la pantalla de inicio?

No como animación en vivo en la pantalla de inicio (Launch Screen). Las pantallas de inicio de iOS son estáticas y se configuran mediante Info.plist o un storyboard sin código personalizado, así que reproduce tu intro de Rive en la primera vista real. Los widgets también se renderizan como capturas, así que trátalos como imágenes estáticas.

Respuestas rápidas de esta guía

• ¿Cómo asigno un input de Rive en SwiftUI?

Fuentes

• Apple runtime, Rive
• Apple runtime: Inputs (legacy), Rive
• Apple runtime: Data binding, Rive
• Data binding migration guide, Rive
• Runtime sizes, Rive
• accessibilityReduceMotion, Apple
• Specifying your app's launch screen, Apple