Rive JS API

NOT YET IMPLEMENTED.

Setup;

1. A global registry to track Rive instances by ID

2. Ref forwarding in components to expose Rive instance methods

3. A manager class that provides the external API

4. Props for ID so components can be registered

What It Would Look Like

1. Global Rive Manager (similar to MediaPlayerManager)

// RiveManager.ts
class RiveManager {
  private instances: Map<string, any> = new Map();

  register(id: string, riveInstance: any) {
    this.instances.set(id, riveInstance);
  }

  unregister(id: string) {
    this.instances.delete(id);
  }

  // Artboard control
  setArtboard(id: string, artboardName: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    
    try {
      instance.artboard = artboardName;
      return true;
    } catch (error) {
      console.error(`Failed to set artboard for ${id}:`, error);
      return false;
    }
  }

  // State machine control
  setStateMachine(id: string, stateMachineName: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    
    try {
      instance.stateMachineName = stateMachineName;
      return true;
    } catch (error) {
      console.error(`Failed to set state machine for ${id}:`, error);
      return false;
    }
  }

  // Input control (the powerful one)
  setInput(id: string, inputName: string, value: number | boolean): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    
    try {
      const input = instance.stateMachineInputs(instance.stateMachineName)
        ?.find((i: any) => i.name === inputName);
      
      if (!input) {
        console.warn(`Input "${inputName}" not found`);
        return false;
      }
      
      input.value = value;
      return true;
    } catch (error) {
      console.error(`Failed to set input for ${id}:`, error);
      return false;
    }
  }

  // Trigger control
  fireTrigger(id: string, triggerName: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    
    try {
      const trigger = instance.stateMachineInputs(instance.stateMachineName)
        ?.find((i: any) => i.name === triggerName && i.type === 'trigger');
      
      if (!trigger) return false;
      
      trigger.fire();
      return true;
    } catch (error) {
      console.error(`Failed to fire trigger for ${id}:`, error);
      return false;
    }
  }

  // Playback control
  play(id: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    instance.play();
    return true;
  }

  pause(id: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    instance.pause();
    return true;
  }

  reset(id: string): boolean {
    const instance = this.instances.get(id);
    if (!instance) return false;
    instance.reset();
    return true;
  }

  // Utility
  getInstanceIds(): string[] {
    return Array.from(this.instances.keys());
  }

  getInstance(id: string): any | null {
    return this.instances.get(id) || null;
  }
}

// Global singleton
export const riveManager = new RiveManager();

// Add to window for external access
declare global {
  interface Window {
    riveManager: RiveManager;
  }
}

if (typeof window !== 'undefined') {
  window.riveManager = riveManager;
}

2. Updated Component (RiveWebGL2.tsx)

export interface RiveWebGL2Props {
  // ... existing props
  id?: string; // ADD THIS - optional ID for external control
}

export const RiveWebGL2: React.FC<RiveWebGL2Props> = ({
  riveUrl,
  id, // ADD THIS
  // ... other props
}) => {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const riveInstanceRef = useRef<any>(null);

  useEffect(() => {
    // ... existing canvas setup

    const loadRive = async () => {
      try {
        const RiveModule = await import('@rive-app/webgl2');
        const { Rive: RiveRuntime, Layout, Fit, Alignment } = RiveModule;

        const riveInstance = new RiveRuntime({
          // ... existing config
        });

        riveInstanceRef.current = riveInstance;

        // Register with manager if ID provided
        if (id) {
          riveManager.register(id, riveInstance);
          console.log(`Rive instance "${id}" registered`);
        }

        // ... rest of setup
      } catch (error) {
        // ... error handling
      }
    };

    loadRive();

    return () => {
      // Unregister on cleanup
      if (id && riveInstanceRef.current) {
        riveManager.unregister(id);
      }
      
      // ... existing cleanup
    };
  }, [urlString, id, /* other deps */]);

  // ... rest of component
};

3. Webflow Props Declaration

// RiveWebGL2.webflow.tsx
export default declareComponent(RiveWebGL2, {
    name: 'Rive WebGL2',
    description: 'Interactive Rive animation player...',
    group: 'Media',
    props: {
        // ... existing props
        
        id: props.ID({
            name: "Component ID",
            tooltip: "Unique ID for external control via JavaScript API (optional)",
            group: "Advanced"
        }),
    },
});

Usage Examples

In Webflow Designer:

1. Add RiveWebGL2 component

2. Set ID to "character-animation"

3. Configure artboard, state machine, etc.

External JavaScript Control:

// In a Webflow embed or custom code

// Change artboard dynamically
window.riveManager.setArtboard('character-animation', 'Walk');

// Switch state machine
window.riveManager.setStateMachine('character-animation', 'Movement');

// Set numeric input (e.g., speed)
window.riveManager.setInput('character-animation', 'speed', 2.5);

// Set boolean input (e.g., isJumping)
window.riveManager.setInput('character-animation', 'isJumping', true);

// Fire a trigger
window.riveManager.fireTrigger('character-animation', 'explode');

// Playback control
window.riveManager.play('character-animation');
window.riveManager.pause('character-animation');
window.riveManager.reset('character-animation');

// Get instance for direct access
const instance = window.riveManager.getInstance('character-animation');
console.log(instance.bounds); // Access Rive instance directly

Event-Driven Example:

// Button click changes character
document.getElementById('hero-button').addEventListener('click', () => {
  window.riveManager.setArtboard('character', 'Hero');
  window.riveManager.fireTrigger('character', 'transform');
});

// Scroll-based animation
window.addEventListener('scroll', () => {
  const scrollPercent = window.scrollY / document.body.scrollHeight;
  window.riveManager.setInput('progress-bar', 'progress', scrollPercent * 100);
});

// Form interaction
document.getElementById('email-input').addEventListener('focus', () => {
  window.riveManager.setInput('form-animation', 'isFocused', true);
});

Real-World Use Cases

1. Interactive Character Selection

// User hovers over character portraits
['warrior', 'mage', 'rogue'].forEach(character => {
  document.getElementById(`${character}-card`).addEventListener('mouseenter', () => {
    window.riveManager.setArtboard('character-preview', character);
    window.riveManager.fireTrigger('character-preview', 'appear');
  });
});

2. Progress/Loading States

// Update loading bar
let progress = 0;
const interval = setInterval(() => {
  progress += 10;
  window.riveManager.setInput('loader', 'percentage', progress);
  
  if (progress >= 100) {
    clearInterval(interval);
    window.riveManager.fireTrigger('loader', 'complete');
  }
}, 200);

3. Form Validation Feedback

// Email validation
const emailInput = document.getElementById('email');
emailInput.addEventListener('blur', () => {
  const isValid = emailInput.validity.valid;
  window.riveManager.setInput('form-feedback', 'isValid', isValid);
  window.riveManager.fireTrigger('form-feedback', isValid ? 'success' : 'error');
});

Advanced: Type-Safe API

For even better DX, you could add TypeScript interfaces:

interface RiveInputs {
  [animationId: string]: {
    [inputName: string]: number | boolean;
  };
}

// Usage with autocomplete
const inputs: RiveInputs = {
  'character': {
    'speed': 2.5,
    'isRunning': true
  }
};

Key Considerations

1. ID Uniqueness: Just like your audio players, ensure IDs are unique across the page

2. Timing: The API only works after components mount. Consider:

// Wait for components to register
window.addEventListener('load', () => {
  console.log('Available Rive instances:', window.riveManager.getInstanceIds());
});

3. Error Handling: The manager returns boolean for success/failure - check these!

4. Performance: Direct Rive API access is synchronous and fast

5. Webflow Compatibility: Works perfectly in published Webflow sites via custom code embeds

Would you like me to implement this Rive manager system for you? It would follow the same pattern as your existing MediaPlayerManager.