---
modificationDate: April 02, 2026
title: Module API Reference
description: An API reference of Expo modules API.
---

<AgentInstructions>

## Submitting Feedback

If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:

curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/modules/module-api/","feedback":"🤖 Agent feedback for docs: <specific, actionable description>","model":"<your model identifier>"}'

Only submit when you have something specific and actionable to report. Replace <your model identifier> with the model you are running as.

</AgentInstructions>

# Module API Reference

An API reference of Expo modules API.

> For the complete documentation index, see [llms.txt](/llms.txt). Use this file to discover all available pages.

The native modules API is an abstraction layer on top of [JSI](https://reactnative.dev/architecture/glossary#javascript-interfaces-jsi) and other low-level primitives that React Native is built upon. It is built with modern languages (Swift and Kotlin) and provides an easy-to-use and convenient API that is consistent across platforms where possible.

## Definition components

As you might have noticed in the snippets on the [Get Started](/modules/get-started) page, each module class must implement the `definition` function. The module definition consists of the DSL components that describe the module's functionality and behavior.

### `Name`

Sets the name of the module that JavaScript code will use to refer to the module. Takes a string as an argument. This can be inferred from the module's class name, but it's recommended to set it explicitly for clarity.

```swift
Name("MyModuleName")
```

### `Constant`

Defines a constant property on the JavaScript object. The property is computed only once when it's first accessed, and subsequent accesses return the cached value.

```swift
Constant("PI") {
  Double.pi
}
```

```kotlin
Constant("PI") {
  Math.PI
}
```

### `Constants`

> **[Deprecated](/more/release-statuses#deprecated):** Use [`Constant`](/modules/module-api#constant) instead.

Sets constant properties on the module. Can take a dictionary or a closure that returns a dictionary.

```swift
// Created from the dictionary
Constants([
  "PI": Double.pi
])

// or returned by the closure
Constants {
  return [
    "PI": Double.pi
  ]
}
```

```kotlin
// Passed as arguments
Constants(
  "PI" to kotlin.math.PI
)

// or returned by the closure
Constants {
  return@Constants mapOf(
    "PI" to kotlin.math.PI
  )
}
```

### `Function`

Defines a native synchronous function that will be exported to JavaScript. Synchronous means that when the function is executed in JavaScript, its native code is run on the same thread and blocks further execution of the script until the native function returns.

#### Arguments

-   **name**: `String` — Name of the function that you'll call from JavaScript.
-   **body**: `(args...) -> ReturnType` — The closure to run when the function is called.

The function can receive up to 8 arguments. This is due to the limitations of generics in both Swift and Kotlin because this component must be implemented separately for each arity.

See the [Argument types](/modules/module-api#argument-types) section for more details on what types can be used in the function body.

```swift
Function("mySyncFunction") { (message: String) in
  return message
}
```

```kotlin
Function("mySyncFunction") { message: String ->
  return@Function message
}
```

```js
import { requireNativeModule } from 'expo-modules-core';

// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');

function getMessage() {
  return MyModule.mySyncFunction('bar');
}
```

### `AsyncFunction`

Defines a JavaScript function that always returns a `Promise` and whose native code is by default dispatched on a different thread than the JavaScript runtime runs on.

#### Arguments

-   **name**: `String` — Name of the function that you'll call from JavaScript.
-   **body**: `(args...) -> ReturnType` — The closure to run when the function is called.

If the type of the last argument is `Promise`, the function will wait for the promise to be resolved or rejected before the response is passed back to JavaScript. Otherwise, the function is immediately resolved with the returned value or rejected if it throws an exception. The function can receive up to 8 arguments (including the promise).

See the [Argument types](/modules/module-api#argument-types) section for more details on what types can be used in the function body.

It is recommended to use `AsyncFunction` over `Function` when it:

-   does I/O bound tasks such as sending network requests or interacting with the file system
-   needs to be run on a different thread, for example, the main UI thread for UI-related tasks
-   is an extensive or long-lasting operation that would block the JavaScript thread which in turn would reduce the responsiveness of the application

```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}

// or

AsyncFunction("myAsyncFunction") { (message: String, promise: Promise) in
  promise.resolve(message)
}
```

```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}

// or

// Make sure to import `Promise` class from `expo.modules.kotlin` instead of `expo.modules.core`.
AsyncFunction("myAsyncFunction") { message: String, promise: Promise ->
  promise.resolve(message)
}
```

```js
import { requireNativeModule } from 'expo-modules-core';

// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');

async function getMessageAsync() {
  return await MyModule.myAsyncFunction('bar');
}
```

It is possible to change the native queue of `AsyncFunction` by calling the `.runOnQueue` function on the result of that component.

```swift
AsyncFunction("myAsyncFunction") { (message: String) in
  return message
}.runOnQueue(.main)
```

```kotlin
AsyncFunction("myAsyncFunction") { message: String ->
  return@AsyncFunction message
}.runOnQueue(Queues.MAIN)
```

#### Kotlin coroutines

`AsyncFunction` can receive a suspendable body on Android. However, it has to be passed in the infix notation after the `Coroutine` block. You can read more about suspendable functions and coroutines on [coroutine overview](https://kotlinlang.org/docs/coroutines-overview.html).

`AsyncFunction` with a suspendable body can't receive `Promise` as an argument. It uses a suspension mechanism to execute asynchronous calls. The function is immediately resolved with the returned value of the provided suspendable block or rejected if it throws an exception. The function can receive up to 8 arguments.

By default, suspend functions are dispatched on the module's coroutine scope. Moreover, every other suspendable function called from the body block is run within the same scope. This scope's lifecycle is bound to the module's lifecycle - all unfinished suspend functions will be canceled when the module is deallocated.

```kotlin
AsyncFunction("suspendFunction") Coroutine { message: String ->
  // You can execute other suspendable functions here.
  // For example, you can use `kotlinx.coroutines.delay` to delay resolving the underlying promise.
  delay(5000)
  return@Coroutine message
}
```

### `Property`

Defines a new property directly on the JavaScript object that represents a native module. It is the same as calling [`Object.defineProperty`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) on the module object.

To declare a read-only property, you can use a shorthanded syntax that requires two arguments:

-   **name**: `String` — Name of the property that you'll use from JavaScript.
-   **getter**: `() -> PropertyType` — The closure to run when the getter for a property was called.

```swift
Property("foo") {
  return "bar"
}
```

```kotlin
Property("foo") {
  return@Property "bar"
}
```

In the case of the mutable property, both the getter and the setter closure are needed (using the syntax below is also possible to declare a property with only a setter):

-   **name**: `String` — Name of the property that you'll use from JavaScript.
-   **getter**: `() -> PropertyType` — The closure to run when the getter for a property was called.
-   **setter**: `(newValue: PropertyType) -> void` — The closure to run when the setter for a property was called.

```swift
Property("foo")
  .get { return "bar" }
  .set { (newValue: String) in
    // do something with new value
  }
```

```kotlin
Property("foo")
  .get { return@get "bar" }
  .set { newValue: String ->
    // do something with new value
  }
```

```js
import { requireNativeModule } from 'expo-modules-core';

// Assume that we have named the module "MyModule"
const MyModule = requireNativeModule('MyModule');

// Obtain the property value
MyModule.foo;

// Set a new value
MyModule.foo = 'foobar';
```

### `View`

Enables the module to be used as a native view. Definition components that are accepted as part of the view definition: [`Prop`](/modules/module-api#prop), [`Events`](/modules/module-api#events), [`GroupView`](/modules/module-api#groupview) and [`AsyncFunction`](/modules/module-api#asyncfunction).

[`AsyncFunction`](/modules/module-api#asyncfunction) in the view definition is added to the React ref of the React component representing the native view. Such async functions automatically receive an instance of the native view as the first argument and run on the UI thread by default.

#### Arguments

-   **viewType** — The class of the native view that will be rendered. Note: On Android, the provided class must inherit from the [`ExpoView`](/modules/module-api#expoview), on iOS it's optional. See [`Extending ExpoView`](/modules/module-api#extending--expoview).
-   **definition**: `() -> ViewDefinition` — A builder of the view definition.

```swift
View(UITextView.self) {
  Prop("text") { ...  }

  AsyncFunction("focus") { (view: UITextView) in
    view.becomeFirstResponder()
  }
}
```

```kotlin
View(TextView::class) {
  Prop("text") { ...  }

  AsyncFunction("focus") { view: TextView ->
    view.requestFocus()
  }
}
```

> Support for rendering SwiftUI views is planned. For now, you can use [`UIHostingController`](https://developer.apple.com/documentation/swiftui/uihostingcontroller) and add its content view to your UIKit view.

### Event observing

### `Events`

Defines event names that the module can send to JavaScript.

> **Note:** This component can be used inside of the [`View`](/modules/module-api#view) block to define callback names. See [`View callbacks`](/modules/module-api#view-callbacks)

```swift
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```

```kotlin
Events("onCameraReady", "onPictureSaved", "onBarCodeScanned")
```

See [Sending events](/modules/module-api#sending-events) to learn how to send events from the native code to JavaScript/TypeScript.

### `OnStartObserving`

Defines the function that is invoked when the first event listener is added.

You need to pass an event name to scope the listener to a specific event. This is useful when you need to set up or tear down resources per-event rather than globally.

```swift
// Called when a listener for "onURLReceived" is added
OnStartObserving("onURLReceived") {
  ... 
}
```

```kotlin
// Called when a listener for "onURLReceived" is added
OnStartObserving("onURLReceived") {
  ... 
}
```

### `OnStopObserving`

Defines the function that is invoked when all event listeners for a given event are removed.

Like `OnStartObserving`, you need to pass an event name to scope the listener to a specific event.

```swift
// Called when listeners for "onURLReceived" are removed
OnStopObserving("onURLReceived") {
  ... 
}
```

```kotlin
// Called when listeners for "onURLReceived" are removed
OnStopObserving("onURLReceived") {
  ... 
}
```

### Lifecycle listeners

### `OnCreate`

Defines module's lifecycle listener that is called right after module initialization. If you need to set up something when the module gets initialized, use this instead of module's class initializer.

### `OnDestroy`

Defines module's lifecycle listener that is called when the module is about to be deallocated. Use it instead of module's class destructor.

### `OnAppContextDestroys`

Defines module's lifecycle listener that is called when the app context owning the module is about to be deallocated.

### `OnAppEntersForeground`

Supported platforms: iOS.

Defines the listener that is called when the app is about to enter the foreground mode.

> **Note:** This function is not available on Android — you may want to use [`OnActivityEntersForeground`](/modules/module-api#onactivityentersforeground) instead.

### `OnAppEntersBackground`

Supported platforms: iOS.

Defines the listener that is called when the app enters the background mode.

> **Note:** This function is not available on Android — you may want to use [`OnActivityEntersBackground`](/modules/module-api#onactivityentersbackground) instead.

### `OnAppBecomesActive`

Supported platforms: iOS.

Defines the listener that is called when the app becomes active again (after `OnAppEntersForeground`).

> **Note:** This function is not available on Android — you may want to use [`OnActivityEntersForeground`](/modules/module-api#onactivityentersforeground) instead.

### `OnActivityEntersForeground`

Supported platforms: Android.

Defines the activity lifecycle listener that is called right after the activity is resumed.

> **Note:** This function is not available on iOS — you may want to use [`OnAppEntersForeground`](/modules/module-api#onappentersforeground) instead.

### `OnActivityEntersBackground`

Supported platforms: Android.

Defines the activity lifecycle listener that is called right after the activity is paused.

> **Note:** This function is not available on iOS — you may want to use [`OnAppEntersBackground`](/modules/module-api#onappentersbackground) instead.

### `OnActivityDestroys`

Supported platforms: Android.

Defines the activity lifecycle listener that is called when the activity owning the JavaScript context is about to be destroyed.

> **Note:** This function is not available on iOS — you may want to use [`OnAppEntersBackground`](/modules/module-api#onappentersbackground) instead.

### `OnActivityResult`

Supported platforms: Android.

Defines the activity lifecycle listener that is called when the activity launched with `startActivityForResult` returns a result.

#### Arguments

-   **activity** — The Android activity that received the result.
-   **payload** — An object containing data about the activity result.
    -   **requestCode**: `Int` — The request code originally supplied to `startActivityForResult`, used to identify the source of the result.
    -   **resultCode**: `Int` — The result code returned by the child activity (for example, `Activity.RESULT_OK` or `Activity.RESULT_CANCELED`).
    -   **data** — An optional intent that carries the result data returned from the launched activity. Can be `null`.

```kotlin
AsyncFunction('someFunc') {
  ... 
  activity.startActivityForResult(someIntent, SOME_REQUEST_CODE)
}

OnActivityResult { activity, payload ->
  ... 
}
```

### `OnNewIntent`

Supported platforms: Android.

Defines the activity lifecycle listener that is called when the activity receives a new intent (for example, from a deep link).

#### Arguments

-   **intent**: `Intent` — The new intent was delivered to the activity. For more information about the `Intent` type, visit: [https://developer.android.com/reference/android/content/Intent](https://developer.android.com/reference/android/content/Intent).

```kotlin
OnNewIntent { intent ->
  val data = intent.data
  // Handle the incoming intent
}
```

### `OnUserLeavesActivity`

Supported platforms: Android.

Defines the activity lifecycle listener called during the activity lifecycle when an activity is about to go into the background because of user choice. For example, when the user presses the Home key, `OnUserLeavesActivity` will be called, but when an incoming phone call causes the in-call Activity to be automatically brought to the foreground, `OnUserLeavesActivity` will not be called on the activity being interrupted.

```kotlin
OnUserLeavesActivity {
  // Your implementation
}
```

### `RegisterActivityContracts`

Supported platforms: Android.

Registers Android [activity result contracts](https://developer.android.com/training/basics/intents/result) that let you launch activities and handle their results in a type-safe way. This is the modern replacement for `startActivityForResult`.

Inside the `RegisterActivityContracts` block, use `registerForActivityResult` to register each contract. The registered launchers can then be used in async functions to launch activities.

```kotlin
class ImagePickerModule : Module() {
  private lateinit var cameraLauncher: ActivityResultLauncher<CameraContractOptions>
  private lateinit var imageLibraryLauncher: ActivityResultLauncher<ImageLibraryContractOptions>

  override fun definition() = ModuleDefinition {
    Name("ImagePicker")

    RegisterActivityContracts {
      cameraLauncher = registerForActivityResult(
        CameraContract(this@ImagePickerModule)
      ) { input, result ->
        handleResult(result, input.options)
      }

      imageLibraryLauncher = registerForActivityResult(
        ImageLibraryContract(this@ImagePickerModule)
      ) { input, result ->
        handleResult(result, input.options)
      }
    }

    AsyncFunction("launchCameraAsync") { options: PickerOptions ->
      cameraLauncher.launch(CameraContractOptions(options))
    }
  }
}
```

## View definition components

The view definition consists of the DSL components that describe the view's functionality and behavior. Those components can only be used within a [`View`](/modules/module-api#view) closure.

### `Name`

Sets the name of the view that JavaScript code will use to refer to the view. Takes a string as an argument. This can be inferred from the view's class name, but it's recommended to set it explicitly for clarity.

```swift
Name("MyViewName")
```

### `Prop`

Defines a setter for the view prop of given name.

#### Arguments

-   **name**: `String` — Name of view prop that you want to define a setter.
-   **defaultValue**: `ValueType` — Optional default value used when the setter is called with `null`.
-   **setter**: `(view: ViewType, value: ValueType) -> ()` — Closure that is invoked when the view rerenders.

This property can only be used within a [`View`](/modules/module-api#view) closure.

```swift
Prop("background") { (view: UIView, color: UIColor) in
  view.backgroundColor = color
}
```

```kotlin
Prop("background") { view: View, @ColorInt color: Int ->
  view.setBackgroundColor(color)
}
```

Prop definition with default value.

```swift
Prop("background", UIColor.black) { (view: UIView, color: UIColor) in
  view.backgroundColor = color
}
```

```kotlin
Prop("background", Color.BLACK) { view: View, @ColorInt color: Int ->
  view.setBackgroundColor(color)
}
```

> **Note:** Props of function type (callbacks) are not supported yet.

### `PropGroup`

Supported platforms: Android.

Batch-registers multiple props that share a common setter pattern. Instead of defining each prop individually, you can register them all at once with a single handler.

Two overloads are available:

-   **Pair-based**: Each prop is a `Pair<String, CustomValueType>`. The handler receives the view, the mapped custom value, and the prop value.
-   **String-based**: Each prop is a name string. The handler receives the view, the positional index, and the prop value.

```kotlin
// Pair-based: map each prop name to a custom value
PropGroup(
  "borderTopColor" to LogicalEdge.TOP,
  "borderBottomColor" to LogicalEdge.BOTTOM,
  "borderLeftColor" to LogicalEdge.LEFT,
  "borderRightColor" to LogicalEdge.RIGHT
) { view: View, edge: LogicalEdge, color: Int? ->
  BackgroundStyleApplicator.setBorderColor(view, edge, color)
}

// String-based: use positional index
PropGroup(
  "borderWidth", "borderLeftWidth", "borderRightWidth",
  "borderTopWidth", "borderBottomWidth"
) { view: View, index: Int, width: Float? ->
  val edge = LogicalEdge.entries[index]
  BackgroundStyleApplicator.setBorderWidth(view, edge, width ?: Float.NaN)
}
```

> **Note:** `PropGroup` is used internally by the CSS prop decorators. Most modules should use individual `Prop` definitions unless they have many props with a shared setter pattern.

### Lifecycle

### `OnViewDidUpdateProps`

Defines the view lifecycle method that is called when the view finished updating all props.

```swift
OnViewDidUpdateProps { view: MyView in
  ... 
}
```

```kotlin
OnViewDidUpdateProps { view: MyView ->
  ... 
}
```

### `OnViewDestroys`

Supported platforms: Android.

Creates a view's lifecycle listener that is called right after the view is no longer used by React Native.

```kotlin
View(MyView::class) {
  OnViewDestroys { view: MyView ->
    ... 
  }
}
```

> **Note:** This function is not available on iOS. You may want to use the destructor of the native view to achieve similar results.

### `AsyncFunction`

Similarly to the [`AsyncFunction`](/modules/module-api#asyncfunction) inside the module definition, you can define functions attached to the view ref to allow direct modification of the native view.

View async functions will always be dispatched on the main queue and can receive the view instance as the first argument.

```swift
View(MyView.self) {
  AsyncFunction("myAsyncFunction") { (view: MyView, message: String) in
    view.displayMessage(message)
  }
}
```

```kotlin
View(MyView::class) {
  AsyncFunction("myAsyncFunction") { view: MyView, message: String ->
    view.displayMessage(message);
  }
}
```

```js
const MyNativeView = requireNativeViewManager('MyView');

function MyComponent() {
  const ref = React.useRef(null);

  React.useEffect(() => {
    ref.current?.myAsyncFunction();
  }, [ref]);

  return <MyNativeView ref={ref} />;
}
```

### View groups

### `GroupView`

Supported platforms: Android.

Enables the view to be used as a view group. Definition components that are accepted as part of the group view definition: [`AddChildView`](/modules/module-api#addchildview), [`GetChildCount`](/modules/module-api#getchildcount), [`GetChildViewAt`](/modules/module-api#getchildviewat), [`RemoveChildView`](/modules/module-api#removechildview), [`RemoveChildViewAt`](/modules/module-api#removechildviewat).

#### Arguments

-   **viewType** — The class of the native view. Note that the provided class must inherit from the Android `ViewGroup`.
-   **definition**: `() -> ViewGroupDefinition` — A builder of the view group definition.

This property can only be used within a [`View`](/modules/module-api#view) closure.

```kotlin
GroupView<ViewGroup> {
  AddChildView { parent, child, index -> ... }
}
```

### `AddChildView`

Supported platforms: Android.

Defines action that adds a child view to the view group.

#### Arguments

-   **action**: `(parent: ParentType, child: ChildType, index: Int) -> ()` — An action that adds a child view to the view group.

This property can only be used within a [`GroupView`](/modules/module-api#groupview) closure.

```kotlin
AddChildView { parent, child: View, index ->
  parent.addView(child, index)
}
```

### `GetChildCount`

Supported platforms: Android.

Defines action the retrieves the number of child views in the view group.

#### Arguments

-   **action**: `(parent: ParentType) -> Int` — A function that returns number of child views.

This property can only be used within a [`GroupView`](/modules/module-api#groupview) closure.

```kotlin
GetChildCount { parent ->
  return@GetChildCount parent.childCount
}
```

### `GetChildViewAt`

Supported platforms: Android.

Defines action that retrieves a child view at a specific index from the view group.

#### Arguments

-   **action**: `(parent: ParentType, index: Int) -> ChildType` — A function that retrieves a child view at a specific index from the view group.

This property can only be used within a [`GroupView`](/modules/module-api#groupview) closure.

```kotlin
GetChildViewAt { parent, index ->
  parent.getChildAt(index)
}
```

### `RemoveChildView`

Supported platforms: Android.

Defines action that removes a specific child view from the view group.

#### Arguments

-   **action**: `(parent: ParentType, child: ChildType) -> ()` — A function that remove a specific child view from the view group.

This property can only be used within a [`GroupView`](/modules/module-api#groupview) closure.

```kotlin
RemoveChildView { parent, child: View ->
  parent.removeView(child)
}
```

### `RemoveChildViewAt`

Supported platforms: Android.

Defines action that removes a child view at a specific index from the view group.

#### Arguments

-   **action**: `(parent: ParentType, child: ChildType) -> ()` — A function that removes a child view at a specific index from the view group.

This property can only be used within a [`GroupView`](/modules/module-api#groupview) closure.

```kotlin
RemoveChildViewAt { parent, index ->
  parent.removeViewAt(child)
}
```

## Argument types

Fundamentally, only primitive and serializable data can be passed back and forth between the runtimes. However, usually native modules need to receive custom data structures — more sophisticated than just the dictionary/map where the values are of unknown (`Any`) type and so each value has to be validated and cast on its own. The Expo Modules API provides protocols to make it more convenient to work with data objects, to provide automatic validation, and finally, to ensure native type-safety on each object member.

### `Primitives`

All functions and view prop setters accept all common primitive types in Swift and Kotlin as the arguments. This includes arrays, dictionaries/maps and optionals of these primitive types.

| Language | Supported primitive types |
| --- | --- |
| Swift | `Bool`, `Int`, `Int8`, `Int16`, `Int32`, `Int64`, `UInt`, `UInt8`, `UInt16`, `UInt32`, `UInt64`, `Float32`, `Double`, `String` |
| Kotlin | `Boolean`, `Int`, `Long`, `Float`, `Double`, `String`, `Pair` |

### `Convertibles`

_Convertibles_ are native types that can be initialized from certain specific kinds of data received from JavaScript. Such types are allowed to be used as an argument type in `Function`'s body. For example, when the `CGPoint` type is used as a function argument type, its instance can be created from an array of two numbers `(x, y)` or a JavaScript object with numeric `x` and `y` properties.

The built-in Convertibles are documented [further below](/modules/module-api#built-in-convertibles).

You can define additional Convertibles by making native Swift types conform to the `Convertible` protocol:

### `Convertible`

Supported platforms: iOS.

`Convertible` is a Swift protocol with one static method:

### `convert(value, appContext)`

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `Any?` | A value from JavaScript to convert |
| `appContext` | `AppContext` | The context object for the currently running Expo app instance |

  

A static method that converts a dynamically typed value from JavaScript to an instance of the Swift type conforming to `Convertible`. Implementers should throw an exception when the given value is invalid or of an unsupported type.

Returns: `Self`

#### Example

```swift
import ExpoModulesCore

extension CMTime: @retroactive Convertible {
  public static func convert(from value: Any?, appContext: AppContext) throws -> CMTime {
    if let seconds = value as? Double {
      return CMTime(seconds: seconds, preferredTimescale: .max)
    }
    throw Conversions.ConvertingException<CMTime>(value)
  }
}
```

In Kotlin, extending an existing type with a protocol isn't possible. To extend available types, you can use the `ModuleConverters` builder:

### `ModuleConverters`

Supported platforms: Android.

On Android, modules can define custom type converters that allow non-standard types to be used as function arguments. Override the `converters()` method in your `Module` class and use the `ModuleConverters` builder to register converters with `.from<SourceType> { }` chains.

```kotlin
class MyModule : Module() {
  override fun converters() = ModuleConverters {
    TypeConverter(CustomType::class)
      .from { number: Int ->
        CustomType.fromInt(number)
      }
      .from { string: String ->
        CustomType.parse(string)
      }
  }

  override fun definition() = ModuleDefinition {
    Name("MyModule")

    // CustomType can now be used as an argument type
    Function("process") { value: CustomType ->
      value.doSomething()
    }
  }
}
```

Each `.from<T> { }` call registers a converter from type `T` to your custom type. At runtime, the framework tries each registered converter until one matches the incoming JavaScript value.

> **Note:** On iOS, use the `Convertible` protocol instead (documented above).

### Built-in Convertibles

Some common iOS types from the `CoreGraphics` and `UIKit` system frameworks are already made convertible.

| Native iOS Type | TypeScript |
| --- | --- |
| `URL` | `string` with a URL. When a scheme is not provided, it's assumed to be a file URL. |
| `CGFloat` | `number` |
| `CGPoint` | `{ x: number, y: number }` or `number[]` with _x_ and _y_ coords |
| `CGSize` | `{ width: number, height: number }` or `number[]` with _width_ and _height_ |
| `CGVector` | `{ dx: number, dy: number }` or `number[]` with _dx_ and _dy_ vector differentials |
| `CGRect` | `{ x: number, y: number, width: number, height: number }` or `number[]` with _x_, _y_, _width_ and _height_ values |
| `CGColor``UIColor` | Color hex strings (`#RRGGBB`, `#RRGGBBAA`, `#RGB`, `#RGBA`), named colors following the [CSS3/SVG specification](https://www.w3.org/TR/css-color-3/#svg-color) or `"transparent"` |
| `Data` | `Uint8Array` , SDK 50+ |

Similarly, some common Android types from packages like `java.io`, `java.net`, or `android.graphics` are also made convertible.

> **Note:** On Android, primitive arrays should be used whenever possible.

| Native Android Type | TypeScript |
| --- | --- |
| `java.net.URL` | `string` with a URL. Note that the scheme has to be provided (URL should not contain any unencoded `%` character) |
| `android.net.Uri``java.net.URI` | `string` with a URI. Note that the scheme has to be provided (URI should not contain any unencoded `%` character) |
| `java.io.File``java.nio.file.Path` (is only available on Android API 26) | `string` with a path to the file |
| `android.graphics.Color` | Color hex strings (`#RRGGBB`, `#RRGGBBAA`, `#RGB`, `#RGBA`), named colors following the [CSS3/SVG specification](https://www.w3.org/TR/css-color-3/#svg-color) or `"transparent"` |
| `kotlin.Pair<A, B>` | Array with two values, where the first one is of type _A_ and the second is of type _B_ |
| `kotlin.ByteArray` | `Uint8Array` , SDK 50+ |
| `kotlin.BooleanArray` | `boolean[]` |
| `kotlin.IntArray``kotlin.FloatArray``kotlin.LongArray``kotlin.DoubleArray` | `number[]` |
| `kotlin.time.Duration` | `number` represents a duration in seconds , SDK 52+ |

### `Records`

_Record_ is a convertible type and an equivalent of the dictionary (Swift) or map (Kotlin), but represented as a struct where each field can have its type and provide a default value. It is a better way to represent a JavaScript object with the native type safety.

```swift
struct FileReadOptions: Record {
  @Field
  var encoding: String = "utf8"

  @Field
  var position: Int = 0

  @Field
  var length: Int?
}

// Now this record can be used as an argument of the functions or the view prop setters.
Function("readFile") { (path: String, options: FileReadOptions) -> String in
  // Read the file using given `options`
}
```

```kotlin
class FileReadOptions : Record {
  @Field
  val encoding: String = "utf8"

  @Field
  val position: Int = 0

  @Field
  val length: Int? = null
}

// Now this record can be used as an argument of the functions or the view prop setters.
Function("readFile") { path: String, options: FileReadOptions ->
  // Read the file using given `options`
}
```

### `Formatter`

> **This feature is [experimental](/more/release-statuses#experimental).**

The Formatter API allows you to customize how a Record is serialized when returned from a native function. This is useful when you need to transform property values before sending them to JavaScript, or conditionally exclude certain properties from the output.

#### Operations

-   **map**: Transform a property's value before serialization.
-   **skip**: Exclude a property from the output entirely.

#### Basic usage

```swift
struct UserInfo: Record {
  @Field var id: Int = 0
  @Field var email: String = ""
  @Field var password: String = ""
}

Function("getUser") {
  let user = UserInfo(id: 1, email: "user@example.com", password: "secret123")

  // Return user without exposing the password
  return user.format { formatter in
    formatter.property("password", keyPath: \.password).skip()
  }
}
```

```kotlin
class UserInfo(
  @Field val id: Int = 0,
  @Field val email: String = "",
  @Field val password: String = ""
) : Record

Function("getUser") {
  val user = UserInfo(id = 1, email = "user@example.com", password = "secret123")

  // Return user without exposing the password
  formatter {
    property(UserInfo::password).skip()
  }.format(user)
}
```

```js
const user = MyModule.getUser();
console.log(user);
// Output: { id: 1, email: "user@example.com" }
// Note: password is not present in the object
```

#### Transforming values with `map`

Use `map` to transform property values before they are sent to JavaScript:

```swift
struct Product: Record {
  @Field var name: String = ""
  @Field var price: Double = 0.0
}

Function("getProduct") {
  let product = Product(name: "Widget", price: 19.99)

  return product.format { formatter in
    // Transform price to include currency symbol
    formatter.property("price", keyPath: \.price).map { value in
      "$\(String(format: "%.2f", value))"
    }
  }
}
```

```kotlin
class Product(
  @Field val name: String = "",
  @Field val price: Double = 0.0
) : Record

Function("getProduct") {
  val product = Product(name = "Widget", price = 19.99)

  formatter {
    // Transform price to include currency symbol
    property(Product::price).map { value ->
      "${"$"}${String.format("%.2f", value)}"
    }
  }.format(product)
}
```

#### Conditional skipping

You can conditionally skip properties based on their values or the record's state:

```swift
struct Settings: Record {
  @Field var theme: String = "light"
  @Field var debugMode: Bool = false
  @Field var apiKey: String? = nil
}

Function("getSettings") {
  let settings = Settings(theme: "dark", debugMode: true, apiKey: "secret")

  return settings.format { formatter in
    // Skip apiKey if nil
    formatter.property("apiKey", keyPath: \.apiKey).skip { value in
      value == nil
    }
  }
}
```

```kotlin
class Settings(
  @Field val theme: String = "light",
  @Field val debugMode: Boolean = false,
  @Field val apiKey: String? = null
) : Record

Function("getSettings") {
  val settings = Settings(theme = "dark", debugMode = true, apiKey = "secret")

  formatter {
    // Skip apiKey if null
    property(Settings::apiKey).skip { value ->
      value == null
    }
  }.format(settings)
}
```

#### Chaining operations

You can chain multiple operations on the same property:

```swift
struct Data: Record {
  @Field var value: Int? = nil
}

Function("getData") {
  let data = Data(value: nil)

  return data.format { formatter in
    formatter.property("value", keyPath: \.value)
      .map { $0 ?? 0 }  // Default to 0 if nil
      .map { $0 * 2 }   // Double the value
  }
}
```

```kotlin
class Data(
  @Field val value: Int? = null
) : Record

Function("getData") {
  val data = Data(value = null)

  formatter {
    property(Data::value)
      .map { it ?: 0 }  // Default to 0 if null
      .map { it * 2 }   // Double the value
  }.format(data)
}
```

### `Enums`

With enums, we can go even further with the above example (with `FileReadOptions` record) and limit supported encodings to `"utf8"` and `"base64"`. To use an enum as an argument or record field, it must represent a primitive value (for example, `String`, `Int`) and conform to `Enumerable`.

```swift
enum FileEncoding: String, Enumerable {
  case utf8
  case base64
}

struct FileReadOptions: Record {
  @Field
  var encoding: FileEncoding = .utf8
  ... 
}
```

```kotlin
// Note: the constructor must have an argument called value.
enum class FileEncoding(val value: String) : Enumerable {
  utf8("utf8"),
  base64("base64")
}

class FileReadOptions : Record {
  @Field
  val encoding: FileEncoding = FileEncoding.utf8
  ... 
}
```

### `Eithers`

There are some use cases where you want to pass various types for a single function argument. This is where Either types might come in handy. They act as a container for a value of one of a couple of types.

```swift
Function("foo") { (bar: Either<String, Int>) in
  if let bar: String = bar.get() {
    // `bar` is a String
  }
  if let bar: Int = bar.get() {
    // `bar` is an Int
  }
}
```

```kotlin
Function("foo") { bar: Either<String, Int> ->
  bar.get(String::class).let {
    // `it` is a String
  }
  bar.get(Int::class).let {
    // `it` is an Int
  }
}
```

The implementation for three Either types is currently provided out of the box, allowing you to use up to four different subtypes.

-   `Either<FirstType, SecondType>` — A container for one of two types.
-   `EitherOfThree<FirstType, SecondType, ThirdType>` — A container for one of three types.
-   `EitherOfFour<FirstType, SecondType, ThirdType, FourthType>` — A container for one of four types.

### `ValueOrUndefined`

> **This feature is [experimental](/more/release-statuses#experimental).**

`ValueOrUndefined` is a wrapper type that allows you to distinguish between a JavaScript `undefined` value and an actual value.

With regular optional types, both `undefined` and `null` from JavaScript are converted to `null` on the native side, making it impossible to tell them apart. `ValueOrUndefined` solves this by preserving the distinction.

#### Properties

### `isUndefined`

Returns `true` if the JavaScript value was `undefined`, `false` otherwise.

Returns: `Bool`

### `optional`

Returns the unwrapped value if present, or `null` if the value was `undefined`.

Returns: `InnerType?`

```swift
Function("configure") { (timeout: ValueOrUndefined<Int>) in
  if timeout.isUndefined {
    // Argument was not provided, use default behavior
  } else if let value = timeout.optional {
    // Argument was provided with a value
  }
}
```

```kotlin
Function("configure") { timeout: ValueOrUndefined<Int> ->
  if (timeout.isUndefined) {
    // Argument was not provided, use default behavior
  } else {
    timeout.optional?.let { value ->
      // Argument was provided with a value
    }
  }
}
```

#### Distinguishing `undefined` from `null`

When using `ValueOrUndefined` with an optional inner type, you can distinguish between three states:

```swift
Function("setName") { (name: ValueOrUndefined<String?>) in
  switch name {
  case .undefined:
    // name argument was not provided
    break
  case .value(let unwrapped) where unwrapped == nil:
    // name was explicitly set to null
    break
  case .value(let unwrapped):
    // name was set to a string value
    print("Name: \(unwrapped!)")
  }
}
```

```kotlin
Function("setName") { name: ValueOrUndefined<String?> ->
  when {
    name.isUndefined -> {
      // name argument was not provided
    }
    name.optional == null -> {
      // name was explicitly set to null
    }
    else -> {
      // name was set to a string value
      println("Name: ${name.optional}")
    }
  }
}
```

```js
import { requireNativeModule } from 'expo-modules-core';

const MyModule = requireNativeModule('MyModule');

MyModule.setName('Alice'); // name is a value
MyModule.setName(null); // name is null (but not undefined)
MyModule.setName(undefined); // name is undefined
```

### `JavaScript values`

It's also possible to use a `JavaScriptValue` type which is a holder for any value that can be represented in JavaScript. This type is useful when you want to mutate the given argument or when you want to omit type validations and conversions. Note that using JavaScript-specific types is restricted to synchronous functions as all reads and writes in the JavaScript runtime must happen on the JavaScript thread. Any access to these values from different threads will result in a crash.

In addition to the raw value, the `JavaScriptObject` type can be used to allow only object types and `JavaScriptFunction<ReturnType>` for callbacks.

```swift
Function("mutateMe") { (value: JavaScriptValue) in
  if value.isObject() {
    let jsObject = value.getObject()
    jsObject.setProperty("expo", value: "modules")
  }
}

// or

Function("mutateMe") { (jsObject: JavaScriptObject) in
  jsObject.setProperty("expo", value: "modules")
}
```

```kotlin
Function("mutateMe") { value: JavaScriptValue ->
  if (value.isObject()) {
    val jsObject = value.getObject()
    jsObject.setProperty("expo", "modules")
  }
}

// or

Function("mutateMe") { jsObject: JavaScriptObject ->
  jsObject.setProperty("expo", "modules")
}
```

## Native classes

### `Module`

A base class for a native module.

#### Properties

### `appContext`

Provides access to the [`AppContext`](#appcontext).

Returns: `AppContext`

#### Methods

### `sendEvent(eventName, payload)`

| Parameter | Type | Description |
| --- | --- | --- |
| `eventName` | `string` | The name of the JavaScript event |
| `payload` | `Android: Map<String, Any?> | Bundle iOS: [String: Any?]` | The event payload |

  

Sends an event with a given name and a payload to JavaScript. See [`Sending events`](#sending-events)

Returns: `void`

### `AppContext`

The app context is an interface to a single Expo app.

#### Properties

### `constants`

Provides access to app's constants from legacy module registry.

Returns: `Android: ConstantsInterface? iOS: EXConstantsInterface?`

### `permissions`

Provides access to the permissions manager from legacy module registry.

Returns: `Android: Permissions? iOS: EXPermissionsInterface?`

### `activityProvider`

Provides access to the activity provider from the legacy module registry.

Returns: `ActivityProvider?`

### `reactContext`

Provides access to the react application context.

Returns: `Context?`

### `hasActiveReactInstance`

Checks if there is an not-null, alive react native instance.

Returns: `Boolean`

### `utilities`

Provides access to the utilities from legacy module registry.

Returns: `EXUtilitiesInterface?`

### `ExpoView`

A base class that should be used by all exported views.

On iOS, `ExpoView` extends the `RCTView` which handles some styles (for example, borders) and accessibility.

#### Properties

### `appContext`

Provides access to the [`AppContext`](#appcontext).

Returns: `AppContext`

#### Extending `ExpoView`

To export your view using the [`View`](/modules/module-api#view) component, your custom class must inherit from the `ExpoView`. By doing that you will get access to the [`AppContext`](/modules/module-api#appcontext) object. It's the only way of communicating with other modules and the JavaScript runtime. Also, you can't change constructor parameters, because provided view will be initialized by `expo-modules-core`.

```swift
class LinearGradientView: ExpoView {}

public class LinearGradientModule: Module {
  public func definition() -> ModuleDefinition {
    View(LinearGradientView.self) {
      ... 
    }
  }
}
```

```kotlin
class LinearGradientView(
  context: Context,
  appContext: AppContext,
) : ExpoView(context, appContext)

class LinearGradientModule : Module() {
  override fun definition() = ModuleDefinition {
    View(LinearGradientView::class) {
      ... 
    }
  }
}
```

## Guides

### Sending events

While JavaScript/TypeScript to Native communication is mostly covered by native functions, you might also want to let the JavaScript/TypeScript code know about certain system events, for example, when the clipboard content changes.

To do this, in the module definition, you need to provide the event names that the module can send using the [Events](/modules/module-api#events) definition component. After that, you can use the `sendEvent(eventName, payload)` function on the module instance to send the actual event with some payload. For example, a minimal clipboard implementation that sends native events may look like this:

```swift
let CLIPBOARD_CHANGED_EVENT_NAME = "onClipboardChanged"

public class ClipboardModule: Module {
  public func definition() -> ModuleDefinition {
    Events(CLIPBOARD_CHANGED_EVENT_NAME)

    OnStartObserving {
      NotificationCenter.default.addObserver(
        self,
        selector: #selector(self.clipboardChangedListener),
        name: UIPasteboard.changedNotification,
        object: nil
      )
    }

    OnStopObserving {
      NotificationCenter.default.removeObserver(
        self,
        name: UIPasteboard.changedNotification,
        object: nil
      )
    }
  }

  @objc
  private func clipboardChangedListener() {
    sendEvent(CLIPBOARD_CHANGED_EVENT_NAME, [
      "contentTypes": availableContentTypes()
    ])
  }
}
```

```kotlin
const val CLIPBOARD_CHANGED_EVENT_NAME = "onClipboardChanged"

class ClipboardModule : Module() {
  override fun definition() = ModuleDefinition {
    Events(CLIPBOARD_CHANGED_EVENT_NAME)

    OnStartObserving {
      clipboardManager?.addPrimaryClipChangedListener(listener)
    }

    OnStopObserving {
      clipboardManager?.removePrimaryClipChangedListener(listener)
    }
  }

  private val clipboardManager: ClipboardManager?
    get() = appContext.reactContext?.getSystemService(Context.CLIPBOARD_SERVICE) as? ClipboardManager

  private val listener = ClipboardManager.OnPrimaryClipChangedListener {
    clipboardManager?.primaryClipDescription?.let { clip ->
      this@ClipboardModule.sendEvent(
        CLIPBOARD_CHANGED_EVENT_NAME,
        bundleOf(
          "contentTypes" to availableContentTypes(clip)
        )
      )
    }
  }
}
```

To subscribe to these events in JavaScript/TypeScript, use [`addListener`](/versions/latest/sdk/expo#addlistenereventname-listener) on the module object returned by `requireNativeModule`. Modules are extending the built-in [`EventEmitter`](/versions/latest/sdk/expo#eventemitter) class. Alternatively, you can use [`useEvent`](/versions/latest/sdk/expo#useeventeventemitter-eventname-initialvalue) or [`useEventListener`](/versions/latest/sdk/expo#useeventlistenereventemitter-eventname-listener) hooks.

```ts
import { requireNativeModule, NativeModule } from 'expo';

type ClipboardChangeEvent = {
  contentTypes: string[];
};

type ClipboardModuleEvents = {
  onClipboardChanged(event: ClipboardChangeEvent): void;
};

declare class ClipboardModule extends NativeModule<ClipboardModuleEvents> {}

const Clipboard = requireNativeModule<ClipboardModule>('Clipboard');

Clipboard.addListener('onClipboardChanged', (event: ClipboardChangeEvent) => {
  alert('Clipboard has changed');
});
```

### View callbacks

Some events are connected to a certain view. For example, the touch event should be sent only to the underlying JavaScript view which was pressed. In that case, you can't use `sendEvent` described in [`Sending events`](/modules/module-api#sending-events). The `expo-modules-core` introduces a view callbacks mechanism to handle view-bound events.

To use it, in the view definition, you need to provide the event names that the view can send using the [Events](/modules/module-api#events) definition component. After that, you need to declare a property of type `EventDispatcher` in your view class. The name of the declared property has to be the same as the name exported in the `Events` component. Later, you can call it as a function and pass a payload of type `[String: Any?]` on iOS and `Map<String, Any?>` on Android.

> **Note:**: On Android, it's possible to specify the payload type. In case of types that don't convert into objects, the payload will be encapsulated and stored under the `payload` key: `{payload: <provided value>}`.

```swift
class CameraViewModule: Module {
  public func definition() -> ModuleDefinition {
    View(CameraView.self) {
      Events(
        "onCameraReady"
      )
      ... 
    }
  }
}

class CameraView: ExpoView {
  let onCameraReady = EventDispatcher()

  func callOnCameraReady() {
    onCameraReady([
      "message": "Camera was mounted"
    ]);
  }
}
```

```kotlin
class CameraViewModule : Module() {
  override fun definition() = ModuleDefinition {
    View(ExpoCameraView::class) {
      Events(
        "onCameraReady"
      )
      ... 
    }
  }
}

class CameraView(
  context: Context,
  appContext: AppContext
) : ExpoView(context, appContext) {
  val onCameraReady by EventDispatcher()

  fun callOnCameraReady() {
    onCameraReady(mapOf(
      "message" to "Camera was mounted"
    ));
  }
}
```

To subscribe to these events in JavaScript/TypeScript, you need to pass a function to the native view as shown:

```tsx
import { requireNativeViewManager } from 'expo-modules-core';

const CameraView = requireNativeViewManager('CameraView');

export default function MainView() {
  const onCameraReady = event => {
    console.log(event.nativeEvent);
  };

  return <CameraView onCameraReady={onCameraReady} />;
}
```

Provided payload is available under the `nativeEvent` key.

## Examples

```swift
public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    Name("MyFirstExpoModule")

    Function("hello") { (name: String) in
      return "Hello \(name)!"
    }
  }
}
```

```kotlin
class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("MyFirstExpoModule")

    Function("hello") { name: String ->
      return "Hello $name!"
    }
  }
}
```

For more examples from real modules, you can refer to Expo modules that already use this API on GitHub:

`expo-battery`[Swift](https://github.com/expo/expo/tree/main/packages/expo-battery/ios)

`expo-cellular`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-cellular/android/src/main/java/expo/modules/cellular), [Swift](https://github.com/expo/expo/tree/main/packages/expo-cellular/ios)

`expo-clipboard`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-clipboard/android/src/main/java/expo/modules/clipboard), [Swift](https://github.com/expo/expo/tree/main/packages/expo-clipboard/ios)

`expo-crypto`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-crypto/android/src/main/java/expo/modules/crypto), [Swift](https://github.com/expo/expo/tree/main/packages/expo-crypto/ios)

`expo-device`[Swift](https://github.com/expo/expo/tree/main/packages/expo-device/ios)

`expo-haptics`[Swift](https://github.com/expo/expo/tree/main/packages/expo-haptics/ios)

`expo-image-manipulator`[Swift](https://github.com/expo/expo/tree/main/packages/expo-image-manipulator/ios)

`expo-image-picker`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-image-picker/android/src/main/java/expo/modules/imagepicker), [Swift](https://github.com/expo/expo/tree/main/packages/expo-image-picker/ios)

`expo-linear-gradient`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-linear-gradient/android/src/main/java/expo/modules/lineargradient), [Swift](https://github.com/expo/expo/tree/main/packages/expo-linear-gradient/ios)

`expo-localization`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-localization/android/src/main/java/expo/modules/localization), [Swift](https://github.com/expo/expo/tree/main/packages/expo-localization/ios)

`expo-store-review`[Swift](https://github.com/expo/expo/tree/main/packages/expo-store-review/ios)

`expo-system-ui`[Swift](https://github.com/expo/expo/tree/main/packages/expo-system-ui/ios/ExpoSystemUI)

`expo-video-thumbnails`[Swift](https://github.com/expo/expo/tree/main/packages/expo-video-thumbnails/ios)

`expo-web-browser`

[Kotlin](https://github.com/expo/expo/tree/main/packages/expo-web-browser/android/src/main/java/expo/modules/webbrowser), [Swift](https://github.com/expo/expo/tree/main/packages/expo-web-browser/ios)