> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# React SDK

> Work with Ninetailed Experiences, instances, and profiles within React and React-based meta-frameworks.

## `<NinetailedProvider>`

The `<NinetailedProvider>` provides a Ninetailed instance to the application. It can accept all of the same instantiation options as a Ninetailed instance to create a new one or accept an existing Ninetailed instance.

```typescript
import type { Ninetailed } from "@ninetailed/experience.js"
import { NinetailedProvider } from "@ninetailed/experience.js-react"
// or import { NinetailedProvider } from '@ninetailed/experience.js-next' 
// or import { NinetailedProvider } from '@ninetailed/experience.js-gatsby'
import type { NinetailedProviderInstantiationProps } from "@ninetailed/experience.js-react"

// Most implementations will rely on the provider to create the Ninetailed instance by passing instantation props
function createWithInstanceProps({createInstanceProps, children}: {createInstanceProps: NinetailedProviderInstantiationProps, children: ReactNode }) {
    return (
        <NinetailedProvider {...createInstanceProps}>
            {children}
        </NinetailedProvider>
    )
}

// However, you can also pass an existing Ninetailed instance to the `ninetailed` prop
// Use this if you need to configure fetchImpl on the NinetailedAPIClient
function createWithNinetailedInstance({ninetailed, children}: {ninetailed: Ninetailed, children: ReactNode }) {
    return (
        <NinetailedProvider ninetailed={ninetailed}>
            {children}
        </NinetailedProvider>
    )
}
```

The provided Ninetailed instance can be retrieved with the [useNinetailed](#useninetailed) hook.

### Types

```typescript
import type {
  Locale,
  NinetailedRequestContext,
  OnErrorHandler,
  OnLogHandler
} from '@ninetailed/experience.js-shared';

import type {
  Ninetailed,
  OnInitProfileId,
  Storage
} from '@ninetailed/experience.js';

import type { NinetailedPlugin } from '@ninetailed/experience.js-plugin-analytics';

type NinetailedProviderInstantiationProps = {
    clientId: string;
    environment?: string;
    buildClientContext?: () => NinetailedRequestContext;
    componentViewTrackingThreshold?: number;
    locale?: Locale;
    onError?: OnErrorHandler;
    onInitProfileId?: OnInitProfileId;
    onLog?: OnLogHandler;
    plugins?: (NinetailedPlugin | NinetailedPlugin[])[];
    requestTimeout?: number;
    storageImpl?: Storage;
    useSDKEvaluation?: boolean;
    url?: string;
}
```

## Hooks

### useExperience

Returns the loading state of an experience and once loaded, the all relevant metadata of the experience including the assigned variant and variant index. This hook powers the React `<Experience>` component exported by the SDKs.

This hook is useful when you need imperative access to the metadata an assigned experience, often in circumstances where you are not intending to render out CMS-sourced content variations. For example, you might be using a feature-flag style experiment where you have no need for the `<Experience>` component, but your application still needs to change behavior and/or send tracking calls based on the assigned `variantIndex`.

```typescript
import { useExperience } from '@ninetailed/experience.js-react';
// or import { useExperience } from '@ninetailed/experience.js-next' 
// or import { useExperience } from '@ninetailed/experience.js-gatsby'
import type { Baseline, ExperienceConfiguration, Profile, Reference } from '@ninetailed/experience.js'

const YourComponent = (props: { 
        baseline: Baseline,
        experiences: ExperienceConfiguration<Variant extends Reference>[]
    }) => {
    const {
        audience,
        baseline, 
        error,
        experience,
        hasVariants,
        isPersonalized,
        loading,
        profile,
        status,
        variant,
        variantIndex
    }: {
        audience: { id: string } | null,
        baseline: Baseline,
        error: Error | null,
        experience: ExperienceConfiguration<Variant> | null,
        hasVariants: boolean,
        isPersonalized: boolean,
        loading: boolean,
        profile: Profile,
        status: 'loading' | 'success' | 'error',
        variant: Variant,
        variantIndex: number,
    } = useExperience(baseline, experiences);
    
    // Go wild
}
```

### useNinetailed

Retrieves the Ninetailed instance from the nearest `<NinetailedProvider>` and all of its instance methods and properties as in the [Ninetailed Instance](/personalization/the-ninetailed-instance) documentation.

```typescript
import { useNinetailed } from '@ninetailed/experience.js-react';
// or import { useNinetailed } from '@ninetailed/experience.js-next' 
// or import { useNinetailed } from '@ninetailed/experience.js-gatsby'

const YourComponent = () => {
    const { 
        debug,
        identify,
        observeElement,
        onIsInitialized,
        onProfileChange,
        page,
        plugins,
        profileState,
        reset,
        track,
        trackComponentView,
        unobserveElement
    } = useNinetailed();
    
    // Go wild
}
```

### useProfile

Retrieves the current profile state from the nearest `<NinetailedProvider>`.

```typescript
import { useProfile } from '@ninetailed/experience.js-react';
// or import { useProfile } from '@ninetailed/experience.js-next' 
// or import { useProfile } from '@ninetailed/experience.js-gatsby'

const GreetingComponent = () => {
    const { 
        error,
        from,
        loading, 
        profile, 
        status 
    }: { 
        error: Error | null, 
        from: 'api' | 'hydrated',
        loading: boolean, 
        profile: Profile | null, 
        status: "error" | "loading" | "success"
    } = useProfile();
    
    if (loading) return <p>Loading...</p>
    
    return <p>Hey {profile?.traits?.firstname ?? 'there'}, nice weather in {profile?.location?.city ?? 'your city'}!</p>
}
```

## Components

### `<Experience>`

The `<Experience>` component is the primary way to render personalized content. It wraps a component and automatically selects the correct variant based on the visitor's audience membership.

```tsx
import { Experience } from '@ninetailed/experience.js-react';
import { ExperienceMapper } from '@ninetailed/experience.js-utils-contentful';

const BlockRenderer = ({ block }) => {
  const experiences = (block.fields.nt_experiences || [])
    .filter(ExperienceMapper.isExperienceEntry)
    .map(ExperienceMapper.mapExperience);

  return (
    <Experience
      id={block.sys.id}
      component={MyComponent}
      experiences={experiences}
      {...block.fields}
    />
  );
};
```

**Props**:

| Prop               | Type                        | Required | Description                                                                        |
| ------------------ | --------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `id`               | `string`                    | Yes      | Unique identifier for the baseline entry (typically `entry.sys.id`)                |
| `component`        | `React.ComponentType`       | Yes      | The component to render with baseline or variant data                              |
| `experiences`      | `ExperienceConfiguration[]` | No       | Mapped experience configurations from `ExperienceMapper.mapExperience()`           |
| `passthroughProps` | `object`                    | No       | Additional props passed to the component that are not part of the Contentful entry |
| `loadingComponent` | `React.ComponentType`       | No       | Component to show while the SDK resolves the variant (useful for SSR/ESR setups)   |

All other props are spread onto the rendered component as the baseline content.

### `<MergeTag>`

The `<MergeTag>` component renders visitor-specific profile data inline. It resolves a dot-notation path against the visitor's profile and renders the value, falling back to a default if unavailable.

```tsx
import { MergeTag } from '@ninetailed/experience.js-react';

<p>
  Welcome back, <MergeTag id="traits.firstName" fallback="friend" />!
  How is <MergeTag id="location.city" fallback="your city" /> today?
</p>
```

**Props**:

| Prop       | Type     | Required | Description                                                                            |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------- |
| `id`       | `string` | Yes      | Dot-notation path into the visitor profile (e.g., `traits.firstName`, `location.city`) |
| `fallback` | `string` | No       | Text to render when the profile value is unavailable                                   |

Merge tags can also be embedded as `nt_mergetag` entries in Contentful rich text fields. See the [Experience SDK](/personalization/experience-sdk#inline-personalization-with-merge-tags) documentation for rich text rendering patterns.

> Work with Ninetailed Experiences, instances, and profiles within React and React-based meta-frameworks.