React

Rive React runtime là một wrapper React bao quanh @rive-app/webgl2 (sử dụng WebGL2 — một API trình duyệt tận dụng GPU của thiết bị để hiển thị đồ họa nhanh, chất lượng cao). Nó cung cấp sẵn component và hook (hàm React cho phép component truy cập logic dùng chung — trong trường hợp này là điều khiển phát lại Rive và phần tử canvas được render) để bạn có thể nhúng animation Rive vào bất kỳ ứng dụng React nào mà không cần viết code canvas cấp thấp. Đã bao gồm kiểu TypeScript.

GitHub: rive-app/rive-react

Bắt đầu

Cài đặt dependency

Chọn gói phù hợp với renderer bạn cần:

@rive-app/react-webgl2 — Dùng Rive Renderer. Hỗ trợ đầy đủ tính năng. (khuyến nghị)
@rive-app/react-canvas — Chỉ Canvas, không có Rive Renderer.
@rive-app/react-canvas-lite — Bundle nhỏ nhất, tính năng hạn chế.

Rive Renderer là engine đồ họa chất lượng cao của riêng Rive. Nó cung cấp hỗ trợ đầy đủ tính năng, bao gồm cả các hiệu ứng hình ảnh nâng cao.

npm i --save @rive-app/react-webgl2

mẹo

Để có chất lượng hiển thị tốt nhất trên Chrome, bạn có thể bật một tính năng đồ họa tùy chọn. Vào chrome://flags và bật WebGL Draft Extensions, sau đó khởi động lại Chrome. Nếu bỏ qua bước này, Rive vẫn hoạt động bình thường — chỉ là sẽ tự động dùng chế độ render kém chính xác hơn một chút.

Sử dụng Rive component

Export mặc định là một React component. Truyền prop src và stateMachines để hiển thị animation Rive.

import Rive from '@rive-app/react-webgl2';

export const Simple = () => (
  <Rive
    src="https://cdn.rive.app/animations/vehicles.riv"
    stateMachines="bumpy"
  />
);

Xem Tham số và Giá trị trả về để biết toàn bộ prop được hỗ trợ.

Sử dụng hook useRive

Dùng hook useRive khi bạn cần truy cập trực tiếp vào instance Rive (ví dụ: để gọi play, pause hoặc đọc state). Nó trả về hai thứ:

rive — instance Rive để gọi các phương thức API.
RiveComponent — React component gắn canvas vào DOM.

import { useRive } from '@rive-app/react-webgl2';

export default function Simple() {
  const { rive, RiveComponent } = useRive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    stateMachines: 'bumpy',
    autoplay: false,
  });

  return (
    <RiveComponent
      onMouseEnter={() => rive && rive.play()}
      onMouseLeave={() => rive && rive.pause()}
    />
  );
}

ghi chú

Rive chỉ khởi tạo sau khi <RiveComponent /> được render, vì nó cần phần tử <canvas> có mặt trong DOM.

Canvas sẽ lấp đầy container của nó. Hãy bọc RiveComponent trong một phần tử có kích thước cố định hoặc truyền className để kiểm soát kích thước.

Render có điều kiện

Hãy bọc useRive trong component riêng của nó khi bạn cần ẩn/hiện animation. Cách này cho phép React unmount component sạch sẽ và khởi tạo lại đúng cách khi mount lại.

// ✅ Đúng: tách useRive ra trong một wrapper
function RiveWrapper() {
  const { rive, RiveComponent } = useRive({ src: '...', stateMachines: '...' });
  return <RiveComponent />;
}

// Trong component cha:
{showRive && <RiveWrapper />}

Xem CodeSandbox này để xem ví dụ thực tế.

Bắt đầu​

Render có điều kiện​

Tài nguyên​

Bắt đầu

Render có điều kiện

Tài nguyên