# Add stickers and AR overlays in React Native

> Apply local image or animated GIF stickers and Cloud Filter AR overlays from a React Native camera screen.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Platform: React Native
SDK version: 2.0.1
Group: guide
Source: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/react-native/

Available platform versions:
- iOS: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/ios.md
- Android: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/android.md
- Web: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/web.md
- React Native: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/react-native.md
- Flutter: https://nosmai.com/docs/effects/guides/stickers-and-ar-overlays/overview/flutter.md



> **Note**
>
> **Feature access**
>
> Runtime face stickers use the native AR overlay slot. Authored masks and 3D
> content also require AR Effects and Cloud Filters to be enabled for the project
> in [Nosmai Console](https://console.nosmai.com/).

## Prerequisites

- A working [React Native quickstart](/docs/effects/quickstart/react-native/)
- A local sticker asset resolved to an absolute `file://` URI
- AR Effects and Cloud Filters enabled for authored overlays

## What a face sticker is

A face sticker is a PNG, JPEG, or animated GIF that your app pins to one of
nine points on the face. Nosmai Effects tracks the face every frame, so the
sticker moves, scales, and tilts with the head.

![Diagram of a face with nine sticker anchor points: above head, forehead, right eye, left eye, eyes, center, nose, mouth, and chin](/images/docs/face-sticker-anchors.webp)

## Choose the content type

| Type | Use it for | Source |
| --- | --- | --- |
| Runtime face sticker | A local PNG, JPEG, or animated GIF supplied by the application | An absolute local `file://` URI |
| Authored AR overlay | Face masks, particles, animated props, and 3D content | A compatible Cloud Filter package |

## Add a runtime face sticker

Resolve the packaged asset to an absolute local file URI before calling the
SDK. Remote HTTP URLs are not accepted by this API.

```tsx
const applied = await NosmaiCameraSdk.setFaceSticker({
  uri: localStickerUri,
  anchor: 'forehead',
  scale: 0.45,
  opacity: 1,
});

if (!applied) {
  throw new Error('Face sticker could not be applied');
}
```

Supported anchors are `center`, `forehead`, `aboveHead`, `leftEye`,
`rightEye`, `eyes`, `nose`, `mouth`, and `chin`.

## Adjust placement

```tsx
await NosmaiCameraSdk.setFaceStickerPlacement({
  anchor: 'nose',
  offsetX: 0,
  offsetY: 0.05,
  scale: 0.4,
  rotationDeg: 0,
  opacity: 1,
});
```

Offsets and scale are relative to the tracked face. Keep opacity between `0`
and `1`, and keep the same anchor when updating a sticker's placement.

## Remove the sticker

```tsx
if (await NosmaiCameraSdk.isFaceStickerActive()) {
  await NosmaiCameraSdk.clearFaceSticker();
}
```

## Apply an authored or 3D overlay

```tsx
const page = await NosmaiCameraSdk.getCloudFilters({
  packageType: 'effect',
  page: 1,
  limit: 20,
});
const overlay = page.filters[0];

if (overlay) {
  const download = await NosmaiCameraSdk.downloadCloudFilter(overlay);
  await NosmaiCameraSdk.applyEffect(download.path);
}
```

Runtime face stickers and authored AR effects share the AR overlay slot. The
most recently applied item replaces the previous item in that slot.

## Verify

Test face loss and return, head rotation, different face distances, navigation,
Fast Refresh cleanup, and both native platforms.

## Common errors

| Symptom | Fix |
| --- | --- |
| Sticker URI is rejected | Resolve the asset to an absolute local `file://` URI before calling the SDK |
| Sticker jumps after an update | Pass the same anchor used when the sticker was first applied |
| Duplicate state updates appear | Remove event subscriptions when the camera screen unmounts |

## Next steps

- [Add an AR face mask in React Native](/docs/effects/guides/effects/add-an-ar-mask/react-native/)
- [Download a Cloud Filter in React Native](/docs/effects/guides/filters/download-a-cloud-filter/react-native/)
- [Read the React Native API reference](/docs/effects/reference/api/react-native/)

## References

- [React Native installation guide](/docs/effects/installation/react-native/)
- [Cloud Filters](/docs/effects/concepts/cloud-filters/)
