> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for the React Native SDK

## Components

### MutaRoot

The root component that initializes the SDK and manages placements.

```tsx theme={null}
<MutaRoot apiKey={string} />
```

#### Props

| Prop     | Type     | Required | Description       |
| -------- | -------- | -------- | ----------------- |
| `apiKey` | `string` | Yes      | Your Muta API key |

## Methods

### Muta.displayPlacement()

Displays a placement in a modal overlay.

```tsx theme={null}
interface DisplayPlacementOptions {
  placementId: string
  loadingScreen?: React.ReactNode
  bgColor: string // Should match your first placement screen's background color
  presentationType?: 'slide' | 'fade' | 'none'
  injectedScreens?: Array<{
    screenName: string
    component: React.ComponentType<CodeScreenProps>
  }>
}

interface CodeScreenProps {
  onContinue: () => void
  onBack: () => void
  variables: any[]
  screenId: string
  screenIndex: number
}

Muta.displayPlacement(options: DisplayPlacementOptions)
```

#### Options

| Option             | Type                          | Required | Description                                                                                                                       |
| ------------------ | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `placementId`      | `string`                      | Yes      | The ID of the placement to display                                                                                                |
| `loadingScreen`    | `React.ReactNode`             | No       | A custom React component to show while the placement is loading                                                                   |
| `bgColor`          | `string`                      | Yes      | Background color that matches your first placement screen. This creates a seamless transition between your app and the placement. |
| `presentationType` | `'slide' \| 'fade' \| 'none'` | No       | Animation style when showing the placement. Defaults to 'slide'.                                                                  |
| `injectedScreens`  | `Array<InjectedScreen>`       | No       | Array of native React components to inject into code screens. See [Code Screens](/sdk/react-native/code-screens) for details.     |

### Muta.on()

Subscribe to Muta events.

```tsx theme={null}
type MutaEventType = 
  | 'flow_started'
  | 'screen_viewed'
  | 'flow_completed'
  | 'flow_abandoned'
  | 'error'
  | string  // Any custom event name
  | '*'    // Listen to all events

type MutaEventCallback = (event: MutaEvent) => void

function on(eventType: MutaEventType, callback: MutaEventCallback): { remove: () => void }
```

#### Parameters

| Parameter   | Type                | Required | Description                                                        |
| ----------- | ------------------- | -------- | ------------------------------------------------------------------ |
| `eventType` | `MutaEventType`     | Yes      | The type of event to listen for. Use '\*' to listen to all events. |
| `callback`  | `MutaEventCallback` | Yes      | The callback function to be called when the event occurs.          |

#### Returns

An object with a `remove` method to unsubscribe from the event.

## Types

### MutaEvent

Base interface for all Muta events.

```tsx theme={null}
interface MutaEvent {
  type: MutaEventType
  timestamp: number
  placementId: string
  flowName?: string
}
```

### FlowStartedEvent

```tsx theme={null}
interface FlowStartedEvent extends MutaEvent {
  type: 'flow_started'
  totalScreens: number
}
```

### ScreenViewedEvent

```tsx theme={null}
interface ScreenViewedEvent extends MutaEvent {
  type: 'screen_viewed'
  screenIndex: number
  totalScreens: number
  screenName?: string
}
```

### FlowCompletedEvent

```tsx theme={null}
interface FlowCompletedEvent extends MutaEvent {
  type: 'flow_completed'
  screenIndex: number
  totalScreens: number
  screenName?: string
  eventData?: {           // Optional: Contains collected variables
    variables: Record<string, any>  // Variable IDs mapped to their values
  }
}
```

### FlowAbandonedEvent

```tsx theme={null}
interface FlowAbandonedEvent extends MutaEvent {
  type: 'flow_abandoned'
  screenIndex: number
  totalScreens: number
  lastScreenIndex: number
  screenName?: string
}
```

### CustomEvent

```tsx theme={null}
interface CustomEvent extends MutaEvent {
  type: string         // Your custom event name
  timestamp: number    // Unix timestamp in ms
  placementId: string  // ID of the placement
  flowName?: string    // Name of the flow (if configured)
  screenIndex?: number // Current screen index
  eventData?: any      // Custom data configured in the editor
}
```

Custom events are configured in the Muta web editor using the "Emit Event" behavior and can have any name you choose (e.g., `'signup_clicked'`, `'plan_selected'`, `'survey_completed'`).

### ErrorEvent

```tsx theme={null}
interface ErrorEvent extends MutaEvent {
  type: 'error'
  message: string
  code?: string
}
```

## Example Usage

```tsx theme={null}
import { Muta, MutaRoot } from '@mutalabs/react-native-muta';

function App() {
  useEffect(() => {
    // Show placement when needed
    Muta.displayPlacement({
      placementId: 'your-placement-id',
      bgColor: '#1a1a1a', // Should match your first placement screen's background color
      presentationType: 'fade' // Optional: customize the animation
    });
  }, []);

  return (
    <>
      <MutaRoot apiKey="your-api-key" />
      {/* Your app content */}
    </>
  );
}
```