# react-native-filament for Native 3D Rendering in React Native

> react-native-filament combines Filament rendering, Bullet3 physics, and a declarative React Native API for native 3D scenes. It fits teams that need GLB assets and separate rendering threads, but source builds add C++ tooling and bundled-engine complexity.

**margelo/react-native-filament** — 🐧 A real-time physically based 3D rendering engine for React Native

- Repository: https://github.com/margelo/react-native-filament
- Website: https://margelo.github.io/react-native-filament/
- Stars: 1,430 · Forks: 63
- Language: C++
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/margelo-react-native-filament

## Why react-native-filament Exists for React Native 3D

react-native-filament addresses a specific gap between ordinary React Native interfaces and applications that need physically based 3D scenes. It exposes a native engine rather than implementing the renderer entirely in JavaScript. The rendering core is C++ Filament, while Bullet3 supplies native physics. The intended users are mobile developers who need 3D models inside React Native and who can accept the platform integration required by a native renderer.

The API models a scene as React elements. The README example places a `FilamentScene` at the application level, a sized `FilamentView` inside it, and camera, lighting, and model components beneath the view. This structure is intended for developers who already use React Native's declarative composition and styling model. It is not a general graphics abstraction that automatically solves arbitrary scene management, asset loading, or game-loop requirements.

The repository description calls the project a real-time physically based 3D rendering engine. Its feature list adds a more concrete scope: native C++ rendering, native C++ physics, GPU backends, rendering on separate threads, a reactive declarative API, documentation, and support for both old and new React Native architectures. Those points place it closer to a native rendering component than to a general-purpose JavaScript 3D library.

## Filament, Bullet3, and Separate Rendering Threads

The architecture is built around two embedded native libraries. Google Filament handles physically based rendering, and Bullet3 handles physics. This matters because the project does not ask an application team to choose between graphics and physics through two unrelated React Native packages. The components live inside the same `FilamentScene` and `FilamentView` model, although the repository excerpt does not document the complete physics API or scene synchronization model.

According to the README, rendering occurs on separate threads. Filament also processes rendering commands in a pool of threads. That differs from the `expo-three` path described in the project comparison, where rendering happens on the JavaScript thread. The documented architecture can keep JavaScript application work separate from the rendering path, but the excerpt does not publish frame timings, memory measurements, scheduling rules, or a way to configure the thread pool. It would therefore be inappropriate to infer a specific performance gain from the architecture alone.

The README identifies Metal and OpenGL or Vulkan as GPU-accelerated backends. On iOS, it specifically says react-native-filament uses Metal. The project supports old and new React Native architectures, which broadens its potential compatibility with applications in different migration states. That statement does not mean every version of React Native is supported. The installation guide and package configuration should be checked for the exact versions and platform combinations used by an application.

## First React Native Scene with a GLB Model

The README directs users to the online installation guide rather than reproducing consumer installation steps in the repository overview. Before adding the package to an application, follow that guide and verify its native setup for the selected React Native architecture and target platforms. No package-manager installation command is documented here, so this article does not invent one.

The first scene example below is reproduced from the README. It imports the scene, view, model, camera, and light components, then composes them as React elements. The `require('./duck.glb')` expression loads the bundled GLB asset. The source also references `model`, although that binding is not defined in the shown snippet and is passed separately to `FilamentView`. A working application therefore needs its own model binding unless the surrounding project supplies one.

```tsx
import { FilamentScene, FilamentView, Model, Camera, DefaultLight } from 'react-native-filament'

function App() {
  return (
    <FilamentScene>
      <FilamentView
        style={{ width: 100, height: 100 }}
        model={model}
      >
        <Camera />
        <DefaultLight >
        <Model source={require('./duck.glb')}>
      </FilamentView>
    </FilamentScene>
  )
}
```

The closing tags shown in the README do not appear complete for `DefaultLight` and `Model`. This is an important documentation limitation for a first-use tutorial. The repository points to `package/example/Shared` and the `AppExamplePaper` and `AppExampleFabric` examples, so those files are the more reliable starting points for current component syntax rather than copying the excerpt blindly. The repository root also lists `examples/Shared/`, `examples/AppExampleFabric/`, and `examples/ExpoExample/`.

## Building Filament and Bullet3 from Source

Contributors who clone the repository need its Git submodules before building the native dependencies. The documented workflow uses Bun commands from the repository's `package` directory. This is a source-development path, not a documented installation sequence for an application that consumes the published npm package.

Clone initialization is recursive so the Filament and Bullet3 sources are available with their own dependencies. The README shows the following command after cloning:

```sh
git submodule update --init --recursive --depth 1
```

The next command installs the workspace's Node modules, including examples. It must be run from `package`:

```sh
cd package
bun i
```

The native libraries are then built with repository scripts. The README lists release and debug alternatives:

```sh
bun build-bullet3
bun build-filament:release
```

For development, the README names `yarn build-filament:debug` as the debug alternative to `bun build-filament:debug`, but it does not give a complete paired sequence. After a successful source build, the documented example app targets are `package/example/AppExamplePaper` and `package/example/AppExampleFabric`. The root workspace package uses `bunx patch-package` as its `postinstall` script and declares the MIT license.

## Prebuilt Filament Binaries and Build Trade-offs

The project offers a shortcut when building Filament from source fails: download prebuilt binaries from the npm package with `bun setup-filament-quick`. According to the README, those binaries are placed in the release build, and edits under `/filament` are ignored because this mode does not build Filament from source. That boundary matters for contributors and maintainers. A local edit to the Filament source cannot affect an application configured to use the prebuilt path.

```sh
bun setup-filament-quick
```

This option can reduce native build friction for an evaluation or integration task. It does not remove the need to understand when the quick setup is selected or whether the resulting binary matches local changes. The README does not document platform selection, binary replacement details, cleanup procedures, or verification commands for this setup path.

A source build is the more relevant path when changing Filament integration itself. The prebuilt path is more relevant when consuming the package with its published native artifacts. Bullet3 still has its own build command, and the README does not offer a corresponding quick setup command for Bullet3. Consequently, failure recovery is documented for Filament, not for the complete native dependency set.

## Metal, Vulkan, and expo-gl Differences

The closest alternative identified by the project is `expo-gl`, usually paired with `expo-three`. This is a useful comparison because both target 3D presentation inside React Native, but they follow different execution and asset paths. react-native-filament uses native C++ Filament and Bullet3, supports GLB files directly, uses Metal on iOS, and performs rendering outside the JavaScript thread according to the README. The `expo-three` comparison path performs rendering on the JavaScript thread, while the README describes `expo-gl` as using Apple's deprecated OpenGL ES framework on iOS.

The format difference is currently narrow but significant. The project says that only GLB is supported yet. Teams whose existing assets are OBJ, FBX, USD, or another format would need to convert or produce GLB files before this API can ingest them. The excerpt does not document compression, texture delivery, animations, materials, transparency, shadows, collision setup, or runtime loading from a network URL.

The threading distinction may appeal to applications where JavaScript work would otherwise compete with rendering. It is not a guarantee of smoother frame delivery on every device, because the project provides no frame-rate, thermal, startup-time, or memory data in the README. The documented facts support a different architecture, not a blanket performance verdict.

## Maintenance Signals, Licensing, and Adoption Boundaries

The repository is not archived. Its last push was on 2026-05-27, and release v1.11.0 carries the same date. Earlier listed releases include v1.9.0 from 2025-10-28 and v1.8.0 from 2025-07-01. These are concrete release and maintenance signals, but they do not establish API stability. The project says it is provided as is, so adopters should treat integration, bug fixes, and feature requests separately from the open-source package itself. Commercial support is directed to Margelo's site.

The repository and root `package.json` identify the MIT license. That covers the project code under its stated terms, but the README also credits example assets from sources with different terms. In particular, `Buster Drone` is listed as licensed under Creative Commons Attribution-NonCommercial 4.0. The example also includes assets attributed to Freepik and Mixamo. The repository overview does not provide enough licensing detail to determine whether every example asset can be reused in a commercial application. Asset review must happen separately from review of the MIT license.

The project is a poor fit for developers who want a web-style, renderer-independent 3D scene, a JavaScript-only workflow, or broad asset-format ingestion without conversion. It is a better fit for mobile teams that can support native builds, need GLB content, value Metal on iOS, and want rendering separated from the JavaScript thread. The incomplete first example and limited model-format statement make the bundled examples and installation guide the adoption gate rather than incidental references.

## Conclusion

react-native-filament is appropriate for teams already working in React Native who need native 3D rendering, GLB assets, or Bullet3 physics and can accept native build work. It is a poor fit for a JavaScript-only mobile stack or a project that needs more than GLB model input without waiting for broader format support. Before adoption, verify the installation guide against the intended React Native architecture, confirm that the required native build path fits the CI environment, and inspect the licensing of every imported model and texture.

## FAQ

### How do I install react-native-filament in a React Native application?

The README links to the installation guide at `https://margelo.github.io/react-native-filament/docs/guides`. The repository overview does not reproduce the application installation command or platform-specific native setup steps.

### Does react-native-filament support OBJ and FBX models?

The README states that only GLB is supported yet. Assets in other formats would need to be converted to GLB before they can be used through the documented `Model` source.

### Does react-native-filament use Bullet3 for physics?

Yes. The feature list identifies native C++ physics using Bullet3. The repository excerpt does not document the exposed physics components or provide a physics example.

## Sources

- [License: MIT](https://github.com/margelo/react-native-filament/blob/main/LICENSE)
- [margelo/react-native-filament on GitHub](https://github.com/margelo/react-native-filament)
- [Project website](https://margelo.github.io/react-native-filament/)
- [README](https://github.com/margelo/react-native-filament/blob/main/README.md)
- [Releases](https://github.com/margelo/react-native-filament/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/margelo-react-native-filament