react-gbajs

GAME BOY ADVANCE EMULATOR

react-gbajs

React wrapper that embeds a Game Boy Advance (GBA) emulator for use in React web apps. It vendores GBA.js and exposes a React context and component to load ROM buffers, control state, and render the emulator in-browser.

Jump to download ↓Jump to setup guide ↓

react-gbajs emulator screenshot.

game boy advancePRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why this project exists

Provides an easy-to-integrate React component and context for running a browser-based GBA emulator (GBA.js) inside React applications, with programmatic control (play, save/restore state, freeze memory addresses) and simple rendering via a default component.

BEST FOR

Best for

Web developers who want to embed a Game Boy Advance emulator in a React site or tool, or ROM-hacking tools and demos that need an embeddable GBA runtime and programmatic emulator control.

The people behind react-gbajs

Background & provenance

react-gbajs is a React-focused wrapper that vendored GBA.js (the JavaScript/browser GBA emulator by endrift and forks). The repository README documents usage, API (GbaContext and ReactGbaJs component), and a sample project. The package is published on npm and source is available under a BSD-2-Clause license on GitHub. The project incorporates and extends GBA.js functionality (save/restore state, freeze addresses) and provides a small React API surface for embedding in modern web projects. The GitHub repository shows source, examples, and a sample app to run locally. (Information verified from the project's GitHub repository and npm package.)

What react-gbajs supports

Nintendo Game Boy Advance (GBA)
Web (modern browsers) via React
Embeds GBA.js emulator core (browser JS/WASM runtime)
ROM buffer input (.gba files supplied as ArrayBuffer/Uint8Array)

Download and availability

OFFICIAL DOWNLOADS

Get react-gbajs

Official source and releases are available from the project's GitHub repository and npm package. Use the repository releases or install from npm (react-gbajs) for integration into a React project.

Get react-gbajs ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

react-gbajs setup guide

Setup note: This guide describes how to add react-gbajs to a React project, load a GBA ROM buffer, and use the provided APIs (GbaProvider, GbaContext, ReactGbaJs). It follows the project's documented usage and sample workflow.

1) Install the package: From your project folder, install via npm or yarn: npm install react-gbajs –save (or yarn add react-gbajs). The package is published on npm and the repository contains a sample app you can inspect or run locally.
2) Wrap your app with GbaProvider: Import and add GbaProvider near the root of your React app: import { GbaProvider } from 'react-gbajs'; Then wrap components that will use the emulator: <GbaProvider>…</GbaProvider>. This provides GbaContext to children.
3) Render the emulator component: Render the default component in your UI where you want the emulator display: import ReactGbaJs from 'react-gbajs'; Use <ReactGbaJs />. The default scale is 1 (240×160). A scale prop adjusts rendered size.
4) Load a ROM buffer and start: Obtain a ROM as an ArrayBuffer/Uint8Array (file input, fetch, or other). Use the GbaContext API: const { play } = useContext(GbaContext); Then call play({ newRomBuffer: myRomBuffer }) to load and start the ROM. play({ restoreState }) is supported to restore emulation state.
5) Save and restore state: Use saveState() from GbaContext to get a serializable snapshot. You can later call play({ restoreState: snapshot }) (optionally with newRomBuffer) to restore execution to that snapshot.
6) Memory freezing and debugging helpers: The wrapper exposes addFreezeAddress({ address, size, value }) and removeFreezeAddress(address) to freeze memory locations for debugging, and frozenAddresses() to list them. These are designed for testing, ROM-hacking, or reproducing conditions.
7) Configure audio, scaling, and logs: ReactGbaJs accepts props: volume (0–1), scale (number), onFpsReported(callback), onLogReceived(callback), and watchLogLevels to control which internal logs invoke the callback. Set volume to 0 to mute; use onFpsReported to monitor renderer performance.
8) Running the provided sample: The repository includes a sample folder. Typical workflow from source (per README): git clone https://github.com/macabeus/react-gbajs.git; npm i; npm run start; then cd sample; npm i; npm run start. The sample demonstrates integration and ROM loading.

Software reminder: The project supplies only the emulator wrapper. You must provide your own GBA ROM images and any required BIOS/firmware yourself; commercial game files and firmware are not included.