@contentful/experiences-react

⚠️ Alpha. Published to npm. APIs are unstable and will change.

The React adapter for the Contentful Experiences SDK. You bring your own React components; it renders Experience payloads from the Experience Delivery API (XDA) with them.

npm install @contentful/experiences-react

This is the only rendering SDK package you install. It re-exports everything you need from @contentful/experiences-sdk-core, @contentful/experiences-design, and @contentful/experiences-client. The optional @contentful/experiences-live-preview package is also customer-facing and provides the framework-neutral live-preview client.

Public API

Authoring

defineComponent<Props>(config); // Type-narrowing identity for component-type configs
defineExperienceTemplate<Props>(config); // Same shape, for coded Experience Template configs

Fetching

fetchExperience(experienceOptions, clientOptions, resolveOptions)  // Async; fetches by Destination path/node id or Experience id and resolves in one call
fetchDestinationSitemap(destinationOptions, clientOptions, paginationOptions?) // Async; lists every routable path in a Destination
fetchPreviewSession(previewSessionOptions, clientOptions, resolveOptions) // Async; fetches and resolves a Preview Session Experience
createClient(options)                       // Functional constructor matching the SDK's option shape
ContentfulViewDeliveryClient                // Re-exported delivery client for advanced use cases
NotFoundError                               // Thrown when the Experience ID or Destination path doesn't exist
DestinationPreviewNotSupportedError         // Thrown when preview is requested for a Destination fetch
PreviewSessionFetchError                   // Thrown when fetching a Preview Session fails
LivePreviewConnectionError                 // Reported when the live-preview connection fails
ContentfulViewDelivery                      // Full error namespace from the delivery client
type ExperienceOptions, ByIdExperienceOptions, ByDestinationPathExperienceOptions,
  ByDestinationNodeIdExperienceOptions, DestinationRedirectResult, DestinationSitemapResult,
  FetchDestinationSitemapOptions, FetchDestinationSitemapPaginationOptions, SitemapPathItem,
  PreviewSessionExperienceOptions, PreviewSessionClientOptions,
  PreviewSessionResolveOptions, ClientOptions, ResolveOptions, CreateClientOptions

Serve pages from a Destination: the URL path is the Destination path. A redirect node comes back as a value, not an error. Preview is not supported on Destinations (it throws DestinationPreviewNotSupportedError); use the by-id form for preview.

const result = await fetchExperience(
  { spaceId, destinationId, path: '/demo/landing' },
  { accessToken },
  { config: experienceConfig }
);
if ('redirect' in result) {
  // follow it: navigate to result.redirect.path
}
// otherwise `result` is a PortableRenderPlan

// Enumerate every routable path, for example to prerender
const sitemap = await fetchDestinationSitemap({ spaceId, destinationId }, { accessToken });
const paths = sitemap.items.map((item) => item.path); // follow sitemap.pages.next for more

Use fetchPreviewSession for the initial render when the Contentful app provides a preview_session_id. It fetches the current Preview Session snapshot and resolves it into a PortableRenderPlan. Use useLivePreview to receive subsequent WebSocket updates:

const plan = await fetchPreviewSession(
  { spaceId, environmentId, sessionId },
  { previewToken },
  { config: experienceConfig }
);

If the Preview Session references resources from other spaces, pass the same encoded resourceResolution value in the previewSessionOptions passed to fetchPreviewSession and useLivePreview.

Resolver

resolveExperience(payload, config, opts?)   // Async; walks payload, runs resolveData, returns a PortableRenderPlan

Live preview

Use useLivePreview when the app should subscribe to Preview Session updates, resolve each payload, and render the resulting plan from data:

const livePreview = useLivePreview({
  previewSessionOptions,
  initialPayload,
  initialPlan,
  resolveOptions: { config: experienceConfig },
});

<ClientExperienceRenderer experience={livePreview.data} config={experienceConfig} />;

For separate access to the raw payload and rendered plan, use useLivePreviewExperience and useExperiencePlan:

const livePreview = useLivePreviewExperience({
  previewSessionOptions: {
    spaceId,
    environmentId,
    previewToken,
    sessionId,
  },
  initialPayload,
});

const plan = useExperiencePlan({
  payload: livePreview.data,
  initialPlan,
  resolveOptions: { config: experienceConfig },
});

<ClientExperienceRenderer experience={plan.data} config={experienceConfig} />;

useLivePreviewExperience returns the latest raw Experience payload. initialPayload seeds the first value. useExperiencePlan turns that payload into the PortableRenderPlan consumed by the renderer and keeps the current rendered experience while an update is being resolved.

The live-preview results also expose error when the Preview Session connection fails. The last valid data remains available.

Renderers

ServerExperienceRenderer; // RSC-friendly renderer
ClientExperienceRenderer; // Client renderer, alias: ExperienceRenderer
MissingComponent; // Default fallback for unregistered component types

Custom renderer (@contentful/experiences-react/custom-renderer)

For hosts that render a plan themselves instead of using ServerExperienceRenderer. resolveNodeProps returns each node's component and merged props, ExperienceNode renders it the way the SDK renderers do, and createExperienceNode renders a node's serializable snapshot where components can't be passed as props. ServerExperienceRenderer and ClientExperienceRenderer render every node through the same resolveNodeProps + ExperienceNode.

resolveNodeProps(node, config); // ResolvedNode: 'resolved' (component, props, design, contentful, snapshot) | 'unregistered'
ExperienceNode; // Renders one resolved node or snapshot exactly as the SDK renderers do
createExperienceNode(components, experienceTemplates?); // ExperienceNode with its registry bound, for snapshots
type ResolvedNode, NodeSnapshot, ExperienceNodeProps;

Styling + runtime context (hooks)

useDesignValues<T>(); // Escape hatch: the same resolved design record that auto-fills props
toCss(design, options?); // Turns a design record into CSSProperties, keeping only real CSS keys
useExperience(); // RenderContext: debug, metadata
useContentfulComponent(); // Raw payload for the enclosing node (or null), including `attribution`
useContentfulExperienceTemplate(); // Same, for an enclosing coded Experience Template node
getTrackingAttributes(attribution); // Props to spread on a node's outermost element for interaction tracking
type ToCssOptions;

Resolved design values are auto-filled onto your component's props by key, alongside content. Styling from those props is the one recommended path. useDesignValues() exposes the same record as an escape hatch. Reach for it only for a nested child that isn't itself a registered component, or for design needed outside the render path (an effect, an imperative measurement) — see Styling components. Token resolution is configured with resolveToken on your Config (type ResolveToken).

Re-exported types and utilities

// From core
type Config, Components, ExperienceTemplates, Registration, ExperienceTemplateRegistration,
type ComponentConfig, ExperienceTemplateConfig,
type ContentfulComponent, ContentfulExperienceTemplate,
type RenderContext, ResolveToken,
type ExperiencePayload, ExperienceNode, ComponentNode, ExperienceTemplateNode,
type PortableRenderPlan, PortableRenderNode, PortableRegistration,
type DesignPropValue, ManualDesignValue, DesignToken, ExperienceContext, ResolveContext,
type ResolverConfig, ResolveExperienceOptions

// From design
isCssProperty, toCssKey, CSS_PROPERTIES

Quick reference

// components/Button.tsx: content + resolved design both arrive as props
'use client';

interface ButtonProps {
  label?: string;
  url?: string;
  backgroundColor?: string; // resolved design, auto-filled
  color?: string;
}

export function Button({ label, url, backgroundColor, color }: ButtonProps) {
  return (
    <a href={url} style={{ background: backgroundColor, color }}>
      {label}
    </a>
  );
}

// lib/experience-config.tsx
import {
  defineComponent,
  type Components,
  type Config,
  type ResolveToken,
} from '@contentful/experiences-react';

import { Button } from './components/Button';

const components: Components = {
  // Bare component, or defineComponent({...}) when you need defaults/resolveData.
  Button: defineComponent({
    resolveData: ({ content }) => ({ url: ensureScheme(content.url) }),
    component: Button,
  }),
};

const resolveToken: ResolveToken = (token) => designTokens[token.value];

export const experienceConfig: Config = { components, resolveToken };

// app/experiences/[id]/page.tsx: in a server component, fetching by Experience id
import { fetchExperience, ServerExperienceRenderer } from '@contentful/experiences-react';

const experience = await fetchExperience(
  { spaceId: process.env.SPACE_ID!, environmentId: 'master', experienceId: id },
  { accessToken: process.env.CDA_TOKEN! },
  { config: experienceConfig }
);
return <ServerExperienceRenderer experience={experience} config={experienceConfig} />;

Slot children

Every slot arrives as a prop named after the slot, holding an array of pre-rendered nodes (ReactNode[]) keyed by the renderer — not a single wrapping node. Drop the array straight into JSX for the common "just render them" case (React renders keyed arrays), or map / filter over it to wrap, reorder, or drop children individually.

// components/Section.tsx
import type { ReactNode } from 'react';

export function Section({ children }: { children?: ReactNode[] }) {
  // Common case — render them all:
  return <div>{children}</div>;

  // Or take control of each child:
  // return (
  //   <div>
  //     {children?.map((child, i) => (
  //       <div className="cell" key={i}>{child}</div>
  //     ))}
  //   </div>
  // );
}

children is not special — it is simply the conventional name for the default slot. Every slot is merged into props under its own name, each as its own ReactNode[], so a component with a header slot just declares header?: ReactNode[] and renders it the same way. This applies identically to coded Experience Templates: a template with a content slot receives a content prop.

For the full getting-started walkthrough, merge-precedence rules, and design rationale, see the root README and AGENTS.md.

License

MIT. See the repository LICENSE and NOTICE for full attribution.

Runtime Experience parameters

By-ID fetchExperience accepts parameters, for example { featuredPosts: { limit: 6, order: '-fields.title' } }. Scalars are strings or numbers; Record leaves have one level. Order is one signed fields.<apiName> or sys.<id> path. Refetch with changed values, then replace the renderer's plan. Exports include ExperienceParameters, ExperienceParameterValue, ExperienceParameterRecord, and ExperienceParameterOrder. See the collection/refetch example.