Getting Started

Installing the library

1. Install react-native-filament:

npm i react-native-filament

2. react-native-filament depends on react-native-worklets-core:

Old Arch

npm i react-native-worklets-core

New arch

On the new arch you need to use the beta version of react-native-worklets-core:

npm i react-native-worklets-core@beta

For react-native-worklets-core its necessary to add a plugin to your babel.config.js as well:

Without reanimated

module.exports = {
  plugins: [
    ["react-native-worklets-core/plugin", { processNestedWorklets: true }],
    // ...
  ],
  // ...
};

When using reanimated

You should already use the reaniamted babel pluginVersions, make sure to add the processNestedWorklets option to it:

module.exports = {
  plugins: [
    ["react-native-reanimated/plugin", { processNestedWorklets: true }],
    // ...
  ],
  // ...
};

3. Update your pods:

cd ios && pod install

4. Start Metro with clean cache:

npm start -- --reset-cache

Good to know

The npm package of react-native-filament is quite huge, around ~400mb. That's because we need to ship all static libraries for all architectures for both android and iOS. The actual size of the library in your downloadable app is around ~4mb.

Configure metro

You'll likely import 3D related files when using react-native-filament. To make sure metro can resolve these files, you need to add the following to your metro.config.js:

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');

const defaultConfig = getDefaultConfig(__dirname)

/**
 * Metro configuration
 * https://metrobundler.dev/docs/configuration
 *
 * @type {import('metro-config').MetroConfig}
 */
const config = {
    resolver: {
        // This makes it possible to import .glb files in your code:
        assetExts: [...(defaultConfig.resolver?.assetExts || []), 'glb']
    }
};

module.exports = mergeConfig(defaultConfig, config);

info

Currently only loading .glb files is supported. You can convert any other 3D models (gltf, obj, FBX, etc) to .glb using blender or online converter tools.

Basic example: Render your first 3D model

For seeing some 3D content on the screen in your app, you need the following things:

• 🏞️ A view to draw the 3D content to (the <FilamentView> component)
• 💡 A light source, otherwise the scene will be black (the <DefaultLight> component)
• 📦 A 3D model file (e.g. a .glb file)
• 📹 A camera through which the scene is observed and projected onto the view (the <Camera> component)

import { FilamentScene, FilamentView, DefaultLight, Model, Camera } from "react-native-filament";
import MyModel from "./MyModel.glb";

function MyScene() {
  return (
    <FilamentScene>

      {/* 🏞️ A view to draw the 3D content to */}
      <FilamentView style={{ flex: 1 }}>

          {/* 💡 A light source, otherwise the scene will be black */}
          <DefaultLight />

          {/* 📦 A 3D model */}
          <Model source={MyModel} />

          {/* 📹 A camera through which the scene is observed and projected onto the view */}
          <Camera />

      </FilamentView>
    </FilamentScene>
  );
}

Additionally you see that we use the <FilamentScene> component to wrap our scene. This is necessary to provide the necessary react context for the scene to work correctly.

Everything that's part of your 3D scene should be rendered as part of the <FilamentView> component.

warning

Trying to render regular react-native components inside the <FilamentView> might work, but is not directly supported and might lead to unexpected behavior. Instead you can render on top of it by using a position: absolute view.

In general react-native-filament leans towards a declartive API that works well with React.