---
title: "Custom elements"
description: "Add a native view, such as a Lottie / Rive animation, an interactive chart, or a camera preview, to a flow screen."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

With a custom element in the Flow & Paywall Builder, you can add a native view to a flow screen. It can be a Lottie / Rive animation, an interactive chart, a map, a camera preview — or any other view that your app can display. Users only see the native view in apps that use the Adapty iOS SDK 4.4 or later. Apps that use the Adapty Android SDK or an SDK for a cross-platform framework, such as Flutter or React Native, show the fallback for every custom element.

To display a native view on a flow screen:

1. [Add a custom element](#add-and-configure) to the screen, and enter its **Type** and **ID**.
2. [Add fallback content](#set-fallback-content) inside the custom element. Users see it when your app doesn't display the view.
3. [Set up the native view in your app](#set-up-your-app-code). Use the Adapty SDK to assign it the same Type and ID.
4. [Publish the flow](#publish-and-test), and test it on a device.
5. [Release the app update with the native view](#what-changes-require-an-app-release). Users of app versions without the native view see the fallback.

:::tip
To display a picture or an animated video, use an [**Image**](custom-media#image) or a [**Video**](custom-media#video) element instead of a custom element. Neither needs code in your app, and you can replace the file without an app release.
:::

## 1. Add a custom element to the screen \{#add-and-configure\}

1. Open the **Add element** panel. In the **Media** group, click **Custom element**.

2. If the native view responds to touch, keep the custom element out of containers that also respond to touch, such as a carousel. That way, a swipe in the native view doesn't move the carousel.
3. In the **Type** field, enter a Type for the kind of native view, such as `lottie_animation`:
   - **Naming rules**: Use only lowercase letters, numbers, and underscores.
   - **Exact match**: The Type must match the one in your app, letter for letter. With any other spelling, users see the fallback.
   - **Suggestions**: The field suggests the Types already used in this flow, not the ones in your app.
4. In the **ID** field, replace the prefilled value, such as `custom_1`, with an ID of your choice, such as `welcome_wave`. The ID distinguishes between custom elements of the same Type.

5. To reserve a set amount of space for the native view, keep the default **Fixed** height. Set it to the height that the view needs.
   - **Shared area**: The native view and the fallback content share the same area.
   - **Alignment**: If the native view is smaller than this area, it appears in the top-left corner by default. To move it, change the alignment in the **Layout** section of the custom element.

   :::important
   With a **Hug** height, a native view without a height of its own, such as a map or a scrolling list, collapses to almost zero height.
   :::

6. (Optional) To cut the native view to the rounded **Corners** of the custom element, in the **Layout** section, select the **Clip content** checkbox.

### Use native views in several custom elements

The following rules apply to the Type and ID of custom elements:

- **Type**: Enter one Type per kind of native view, such as `lottie_animation` for a Lottie player and `map` for a map.
- **ID**: Within one Type, assign a unique ID per piece of content, such as `streak_ring` and `welcome_wave` for two Lottie animations. Your app reads the ID to pick the content. If two custom elements on one screen have the same Type and ID, the **ID** field shows a warning: *Same type and ID as another element on this screen.* You can still publish the flow.
- **Element copies**: When you duplicate or paste an element, or add a [tab](builder-tabs), the builder renames each copied ID that's already taken within the screen or component. For example, `custom_1` becomes `custom_2`, and `hero` becomes `hero_2`. Make sure that the code of your app references the correct ID.

## 2. Add fallback content \{#set-fallback-content\}

Users see the fallback in place of the native view when:

- Their version of your app doesn't include the view code.
- Your app uses the Adapty Android SDK, an SDK for a cross-platform framework, or an Adapty iOS SDK version earlier than 4.4.
- The custom element's Type and ID do not match a view in your app code.
- Your app code matches the Type and ID but returns no view. For example, the view needs a file that isn't on the device, or a permission that the user denied.

To set the fallback, add elements to the custom element container. When the native view doesn't appear, a custom element without a fallback stays empty.

The Flow & Paywall Builder can't run your app code, so its canvas only shows the fallback. The [preview in the Adapty mobile app](paywall-device-compatibility-preview#preview-on-devices) shows the fallback too. To preview the native view, [test the flow on a device](#publish-and-test) in a build of your app.

:::important
Keep navigation buttons, purchase buttons, and other essential UI parts outside the custom element. Users see either the native view or the fallback, never both.
:::

You can't add a **Footer**, a **Sliding sheet**, or a **Bottom Sheet** inside a custom element.

## 3. Set up the native view in your app \{#set-up-your-app-code\}

When a screen with a custom element opens, the Adapty SDK passes the element's Type and ID to a resolver function in your app code. The resolver returns one of the following:

- **The view that matches the Type and ID**: Users see the native view. In the code, spell the Type and ID exactly as in the builder.
- **No view**: Users see the fallback. For example, return no view when a file that the view needs isn't on the device.

For the iOS code, follow [Display custom elements with the iOS SDK](ios-flow-custom-elements). It shows how to write the resolver and test the native view on a device.

:::tip
A native view can visualize user data, such as answers from an earlier flow. See [Show an interactive weight goal chart in a paywall](custom-element-interactive-chart).
:::

## 4. Publish and test the flow \{#publish-and-test\}

To [publish the flow](builder-save-publish), make sure that every custom element has a Type that follows the [naming rules](#add-and-configure). You can publish the flow before you release the app. Until users update the app, they see the fallback.

An error in the native view can crash the app. Before you release the app, test every screen that has a custom element in a build with the native view. To test a flow that real users don't see yet, add it to a [placement](create-placement) that this build requests and your released app doesn't. To see the latest published flow instead of a cached one, register the device as a [test device](test-devices). For the full procedure, read [Test on a device](ios-flow-custom-elements#test-on-a-device).

## What changes require an app release \{#what-changes-require-an-app-release\}

Native views are part of the code of your app. To change a native view, release an app update. To change the fallback content or any setting of a custom element except its Type and ID, publish the flow.

| Changed content | What you do | Users who haven't updated the app see |
|---|---|---|
| The native view of an existing custom element, such as a different animation | Release an app update with the new native view | The previous native view, if their app version includes it |
| A native view for a new custom element | Release an app update with the new native view. Add a custom element with the new Type and ID, and publish the flow | Fallback content |
| An existing native view on another screen, in another flow, or in an A/B test | Add a custom element with the same Type and ID, and publish the flow. No app update needed if your [app-wide resolver](ios-flow-custom-elements#set-an-app-wide-resolver) returns the view | The native view, if their app version includes it |
| The Type or ID of a custom element | Release an app update with a native view for the new Type and ID, and publish the flow | Fallback content |
| Fallback content, other settings of a custom element | Publish the flow. No app update needed | The updated content |

## Examples

Each recipe shows the setup in the builder and the code for your app:

- [Show user progress with a Lottie animation](custom-element-lottie-animation): A ring that fills as a streak grows.
- [Show an interactive weight goal chart in a paywall](custom-element-interactive-chart): A weight goal chart, in the paywall flow that follows the onboarding flow.
- [Show nearby places on a map in a flow](custom-element-map): A map of fitness centers near each user.

## Troubleshooting

- **Users see the fallback instead of the native view**: Make sure that the Type and ID match the ones in your app, letter for letter. Users of app versions without the view see the fallback until they update the app. To find the cause in the code, follow [Test on a device](ios-flow-custom-elements#test-on-a-device) in the iOS guide.
- **Users see an empty area**: [Add a fallback](#set-fallback-content) and publish the flow. If you still see an empty area on a [test device](test-devices), the native view appears without its content. Make sure that the resolver returns `nil` when the content is missing, as in [Set conditions for fallback content](ios-flow-custom-elements#set-conditions-for-fallback-content).
- **The native view doesn't fit the custom element**: Make sure that your app fits the view to the area of the custom element. To cut the view to the rounded **Corners**, in the **Layout** section, select the **Clip content** checkbox.