munim-xr

Native ARKit and ARCore sessions for Expo and React Native, powered by Nitro Modules.

iOS

Android

GitHub

npm

Overview

munim-xr provides one typed Nitro Hybrid View for world-tracked augmented reality on iOS and Android. It renders the native ARKit or ARCore camera feed and exposes session lifecycle, camera poses, tracking state, plane detection, hit testing, native anchors, light estimation, optional depth, and PNG snapshots to Expo development builds and bare React Native apps.

Installation

Terminal

npx expo install munim-xr react-native-nitro-modules

For bare React Native without Expo: npm install munim-xr react-native-nitro-modules

Usage

Start a native XR session

import { useMemo, useRef } from 'react'
import { StyleSheet } from 'react-native'
import { callback } from 'react-native-nitro-modules'
import {
  checkAvailability,
  requestCameraPermission,
  requestInstall,
  XRView,
  type XRViewRef,
} from 'munim-xr'

const xrRef = useRef<XRViewRef | null>(null)
const hybridRef = useMemo(
  () => callback((ref: XRViewRef) => (xrRef.current = ref)),
  []
)

async function startXR() {
  if (!(await requestCameraPermission())) return
  const availability = await checkAvailability()
  if (availability === 'not-installed' || availability === 'update-required') {
    if (!(await requestInstall())) return
  }
  if (availability === 'unsupported') return
  await xrRef.current?.start()
}

<XRView
  depthEnabled={false}
  frameCallbackFps={15}
  hybridRef={hybridRef}
  lightEstimationEnabled
  planeDetection="both"
  style={StyleSheet.absoluteFill}
/>

Requirements

React Native 0.78+ with the New Architecture, react-native-nitro-modules 0.36.5+, iOS 15.1+ on an ARKit-capable device, or Android API 24+ with Google Play Services for AR. A native development build is required; Expo Go cannot load this package.

Platform notes

iOS

Uses ARKit and ARSCNView on iOS 15.1+. Supports world tracking, plane raycasts, native anchors, ambient light, optional Scene Depth, and PNG snapshots. The iOS Simulator can compile the app but does not provide a normal world-tracking session.

Android

Uses ARCore 1.54 on Android API 24+. Supports camera rendering, plane/depth/point hit results, native anchors, ambient light, optional Automatic Depth, snapshots, and the Google Play Services for AR install flow.

API

Methods

isSupported() / checkAvailability()

Checks native ARKit or ARCore support. The asynchronous result distinguishes supported, unsupported, not-installed, update-required, and unknown states.

Returns: boolean / Promise<XRAvailability>

requestCameraPermission() / requestInstall()

Requests Android camera permission and, when necessary, starts the native ARCore install or update flow. iOS asks for camera access when the session starts.

Returns: Promise<boolean>

XRView.start() / pause() / reset()

Starts, pauses, or resets the native world-tracking session through the captured XRView Hybrid reference.

Returns: Promise<void> / void

XRView.hitTest(normalizedX, normalizedY)

Tests a normalized screen point against native tracked or estimated geometry and returns ordered hit poses.

Returns: Promise<XRHitResult[]>

XRView.createAnchor(pose) / removeAnchor(id) / getAnchors()

Creates and manages native session anchors using typed world poses.

Returns: Promise<XRAnchor> / void / XRAnchor[]

XRView.getCameraPose()

Returns the latest native camera position, orientation, and transform matrix when available.

Returns: XRPose | undefined

XRView.captureSnapshot()

Captures the rendered native XR view as PNG and returns a temporary or cache file path.

Returns: Promise<string>

Types

XRPose

A native world-space transform measured in meters.

Property	Type	Description
position	XRVector3	World-space x, y, and z translation.
orientation	XRQuaternion	World-space x, y, z, and w rotation.
matrix	number[]	Sixteen column-major transform values.

XRFrame

Throttled frame data sent from the native session.

Property	Type	Description
timestamp	number	Native frame timestamp in seconds.
trackingState	XRTrackingState	Current camera tracking quality.
cameraPose	XRPose	Current native camera transform.
lightIntensity?	number	Ambient intensity when light estimation is valid.

XRPlane

A native tracked surface delivered through plane callbacks.

Property	Type	Description
id	string	Session-stable plane identifier.
alignment	horizontal \| vertical \| unknown	Detected plane alignment.
classification	XRPlaneClassification	Best available semantic classification.
center	XRVector3	Plane center relative to its pose.
extent	XRVector3	Estimated surface extent in meters.
pose	XRPose	Plane transform in world space.

Enums

XRAvailability

supported— Native XR is installed and supported.
unsupported— The OS or hardware cannot run the session.
not-installed— Google Play Services for AR must be installed.
update-required— Google Play Services for AR must be updated.
unknown— The native support check has not produced a definitive result.

XRView event props

onReady— The first tracked frame is available.
onFrame— A throttled pose and light-estimate frame arrived.
onTrackingStateChange— Native tracking quality changed.
onPlaneDetected / onPlaneUpdated / onPlaneRemoved— A tracked surface changed.
onError— The native session reported an error.

Features

•Native XR view - ARSCNView on iOS and an ARCore OpenGL camera surface on Android
•World tracking - Receive native camera position, orientation, and column-major pose matrices
•Plane detection - Detect horizontal and vertical planes with add, update, and remove callbacks
•Hit testing - Raycast normalized screen coordinates against native tracked geometry
•Native anchors - Create, inspect, and remove persistent anchors from hit or custom poses
•Tracking callbacks - React to unavailable, limited, and normal tracking states
•Light estimation - Receive ambient intensity with throttled native frame callbacks
•Optional depth - Enable ARKit Scene Depth or ARCore Automatic Depth when supported
•Snapshots - Capture the rendered XR view to a local PNG path
•Runtime checks - Detect ARKit/ARCore support and request ARCore installation or updates
•Expo config plugin - Configure camera permission and optional or required AR device capabilities
•Nitro Modules - Fully typed Swift, Kotlin, C++, and TypeScript bindings

For the latest API reference, usage examples, and troubleshooting, visit the GitHub repository and npm package page.