React SDK

The Uniform SDK for React provides two complementary packages for building personalized, composable experiences in any React application:

• @uniformdev/canvas-react -- Renders Uniform Canvas compositions as React component trees with support for slots, parameters, rich text, and visual editing.
• @uniformdev/context-react -- Provides React bindings for Uniform Context, enabling personalization, A/B testing, visitor scoring, and behavior tracking.

These packages work with any React setup -- Vite, Remix, Gatsby, a custom SSR server, or any other React-based architecture. For Next.js App Router projects, use the dedicated @uniformdev/next-app-router package instead.

Getting started#

Prerequisites#

• React 18+
• Node.js 18+
• A Uniform project with compositions and component types configured

Starter projects#

Two official starter projects are available on GitHub to help you get up and running quickly:

Both starters include sample content that you can push to your own Uniform project with npm run uniform:push.

Install packages#

Peer dependencies#

Both React packages require react and react-dom as peer dependencies. If you use client-side visibility rules via the useClientConditionsComposition hook, you also need immer >= 10:

Canvas#

Canvas is Uniform's visual composition system. The @uniformdev/canvas-react package provides React components to render Canvas compositions -- turning the JSON composition tree from the Uniform API into a rendered React component tree.

Core concepts#

A Canvas composition is a tree structure where:

• The root is a composition instance (e.g., a "Page" component)
• Each component can have slots -- named locations where child components are placed
• Each component has parameters -- typed values (text, rich text, images, links, etc.) configured in the Uniform dashboard
• Personalization and A/B test containers are special system components that wrap variants

The React SDK walks this tree and renders each node using a component resolver -- a function you write that maps Uniform component types to your React components.

Fetching compositions#

Before rendering, you need to fetch the composition data from the Uniform API. Use RouteClient from @uniformdev/canvas:

Rendering a composition#

The UniformComposition component is the entry point for rendering a composition tree. It takes the composition data and a component resolver, and renders the full component tree:

UniformComposition props#

Component resolution#

The component resolver is a function that receives a ComponentInstance and returns the React component to render. This is how you map Uniform component types to your React components:

Alternative: Component store registration#

Instead of a switch statement, you can use the component store pattern to register components declaratively:

Then use componentStoreResolver as your resolver:

The store supports variant-specific registration:

Resolution priority: exact type + variant match, then type-only match, then the default fallback.

ComponentProps#

Every component rendered by Canvas receives ComponentProps. This type gives you access to the raw component data:

The ComponentProps<T> type extends your custom props with:

Parameter values are automatically extracted from component.parameters[id].value and flattened onto the component props by the SDK's internal convertComponentToProps helper. So if your Canvas component has a parameter named title with value "Hello", your component receives { title: "Hello", component: { ... } }.

UniformSlot#

UniformSlot renders child components placed in a named slot:

UniformSlot props#

Custom wrapper for slot items#

Use wrapperComponent to wrap each child in the slot with custom markup:

Empty slot placeholder#

Show fallback content when a slot has no children:

UniformText#

UniformText renders text parameters with built-in support for inline editing in the Uniform visual editor:

UniformText props#

Custom rendering#

Use the render prop to transform the parameter value before display:

UniformRichText#

UniformRichText renders rich text parameters with full formatting support including headings, lists, links, images, tables, and text formatting:

UniformRichText props#

Custom rich text node rendering#

Override how specific rich text nodes are rendered:

The SDK includes built-in renderers for all standard rich text node types: paragraphs, headings (h1-h6), lists, list items, links, images/videos/audio assets, tables, line breaks, tabs, and formatted text (bold, italic, underline, strikethrough, code, subscript, superscript).

Accessing raw parameter values#

When you need parameter values directly (for non-visual use like URLs, booleans, or conditional logic), access them from the component prop:

getParameterAttributes helper#

For advanced inline editing scenarios, getParameterAttributes returns the data attributes needed to mark an element as editable by the Uniform visual editor:

This is useful when you cannot use UniformText but still want inline editing support.

Hooks#

useUniformCurrentComposition#

Returns the data and configuration from the nearest UniformComposition ancestor:

Return value:

useUniformCurrentComponent#

Returns the data from the nearest UniformComponent ancestor (the currently rendering component):

useUniformContextualEditing#

Enables contextual editing -- the two-way communication between your React app and the Uniform visual editor. When a content author edits a composition in the Uniform dashboard, this hook receives live updates and re-renders the composition in real time:

useUniformContextualEditingState#

Provides information about the current contextual editing state, such as which component is selected in the editor:

useClientConditionsComposition#

Evaluates client-side visibility rules on a composition and returns a filtered composition with invisible components removed:

This hook uses immer internally for immutable updates and reads the current visitor's quirks from the Uniform Context to evaluate visibility conditions.

Visual editing#

The Uniform visual editor allows content authors to edit compositions directly in the browser. The React SDK supports this with:

1. Contextual editing -- Live preview updates when editing in the Uniform dashboard
2. Inline editing -- Direct text editing within the rendered page (via UniformText and UniformRichText)
3. Component selection -- Click-to-select components in the visual editor

To enable contextual editing, pass the contextualEditingEnhancer prop to UniformComposition:

The SDK automatically:

• Detects when the page is loaded inside the Uniform visual editor
• Sets up a message channel for live composition updates
• Adds data attributes to components and parameters for editor interaction
• Provides the isContextualEditing flag via useUniformCurrentComposition

Setting up the visual editor preview#

To enable the Uniform visual editor (contextual editing) with a React app, your server must handle two special requests from the Uniform dashboard:

1. Config check -- The editor pings your preview URL to check capabilities (e.g., whether a playground route exists).
2. Preview route -- When a content author opens the visual editor, the dashboard loads your app inside an iframe. On preview requests, your server should skip fetching composition data and instead return a page with an empty composition stub -- the editor sends the actual composition data over a postMessage channel.

Here is a complete Express server setup demonstrating both (from the react-vite-ssr starter):

Configuring the preview URL in Uniform#

After setting up your server, configure the preview URL in your Uniform project so the visual editor knows where to load your app:

1. Go to Settings > Canvas Settings > Preview in your Uniform project.
2. Add a preview URL pointing to your preview route, for example: http://localhost:5173/api/preview.
3. Optionally configure preview viewports (Desktop, Tablet, Mobile) for responsive previewing.

The react-vite-ssr starter includes a pre-configured preview URL and viewport definitions in the uniform-data/ folder that are pushed to your project with npm run uniform:push.

UniformPlayground#

UniformPlayground is a special component for previewing individual components and patterns in the Uniform dashboard. It renders with an empty composition and supports contextual editing:

Context#

Context is Uniform's personalization and optimization engine. The @uniformdev/context-react package provides React components and hooks that integrate the Context engine into your React application, enabling personalization, A/B testing, visitor scoring, and behavior tracking.

Using Context without Canvas#

You don't need Canvas compositions to use Uniform personalization. The @uniformdev/context-react package works standalone in any React app -- you can add personalization, A/B testing, and visitor scoring to an existing React application without adopting Canvas or changing your rendering architecture.

The react-starter-cra starter demonstrates this approach with a client-side React app that uses React Router for page navigation and Uniform Context for personalization. No Canvas compositions, no @uniformdev/canvas packages -- just Context.

In this pattern, you track enrichments programmatically inside your page components:

This approach is ideal when you want to:

• Add personalization to an existing React SPA without a CMS
• Use Uniform signals and scoring with your own component architecture
• Implement programmatic enrichment tracking based on user navigation patterns

Setting up UniformContext#

The UniformContext provider wraps your application and provides the Context instance to all child components:

Persisting visitor data with CookieTransitionDataStore#

By default, visitor scores and quirks are stored in memory and lost on page reload. Use CookieTransitionDataStore to persist visitor data across sessions via cookies:

Enabling debug logging#

Use enableDebugConsoleLogDrain during development to log all Context activity (signal evaluations, score changes, enrichment tracking) to the browser console:

UniformContext props#

Transfer state for SSR#

When server-rendering, the UniformContext automatically injects a <script> tag containing the serialized context state. The client picks this up during hydration so that the visitor's scores and quirks are preserved without a flash of unpersonalized content:

Creating the manifest#

The personalization manifest defines your project's signals, enrichments, quirks, and A/B tests. There are several ways to create it:

Option 1: Hardcode for development

Option 2: Download via CLI (recommended for production)

Then import it:

Option 3: Fetch at runtime

Personalization#

The Personalize component selects and renders content variants based on the visitor's scores, quirks, and other classification data.

How it works#

1. You define multiple variations of a content component, each tagged with personalization criteria (enrichment tags/scores).
2. The Personalize component calls context.personalize() to evaluate the visitor's current scores against each variation's criteria.
3. The winning variation(s) are rendered. If no variation matches, the default (first) variation is shown.

Personalize props#

The rendered component receives all variation properties plus a personalizationResult object:

Wrapper component#

Use wrapperComponent to add conditional styling or tracking based on whether personalization occurred:

A/B testing#

The Test component implements A/B testing by selecting a single variant based on test distribution percentages:

Test props#

Behavior tracking#

Track visitor interactions to build up enrichment scores that drive personalization. The SDK provides two tracking components:

Track (viewport-based)#

Track tracks visitor behavior when content enters the viewport using IntersectionObserver:

Track props#

TrackFragment (page load-based)#

TrackFragment tracks immediately on page load / route change without adding a wrapper element:

Both tracking components:

• Track once per URL change per component instance (no duplicate tracking)
• Do not track when inside a Personalize component (prevents double-counting)
• Call context.update({ enrichments }) to update the visitor's scores

Hooks#

useUniformContext#

Accesses the Uniform Context instance from the nearest UniformContext provider:

By default, this hook throws an error if no UniformContext provider is found. To make it optional:

useScores#

Provides reactive access to the visitor's current scores. The component re-renders automatically when scores change:

Returns a ScoreVector -- an object mapping signal names to numeric score values.

useQuirks#

Provides reactive access to the visitor's current quirks. Re-renders when quirks change:

Returns a Quirks object -- key-value pairs representing visitor attributes.

Updating quirks programmatically#

Use the Context instance to set quirks from user interactions:

useIsPersonalized#

Determines if the current component is inside a Personalize component:

Edge-side rendering#

The Context React SDK supports edge-side personalization and testing. When outputType is set to 'edge', the Personalize and Test components emit all variations wrapped in special HTML tags. An edge worker (Cloudflare, Vercel, Netlify, Akamai) then selects the winning variant before delivering the page to the visitor:

In edge mode:

• Personalize renders all variations with metadata tags for edge selection
• Test renders all variations with test distribution metadata
• The edge worker evaluates scores/quirks and strips non-winning variants from the HTML

See the edge-side personalization guide for detailed setup instructions.

Full project example#

Here is a complete example showing how to wire up both Canvas and Context in a React + Vite SSR project.

Project structure#

App component#

Component resolver#

Page component#

Hero component#

API client#

Server entry#

Client entry#

Import reference#

@uniformdev/canvas-react#

@uniformdev/context-react#

@uniformdev/canvas#

@uniformdev/context#

Recipes#

Recipe: Adding Uniform to an existing React + Vite project#

1. Install packages:

2. Create environment variables (.env):

3. Create the manifest file. Download it via CLI:

4. Create the API client (src/uniform/api.ts):

5. Create the component resolver (src/resolveRenderer.ts):

6. Wrap your app with UniformContext and render compositions with UniformComposition:

7. Add CLI scripts to package.json:

Recipe: Component with personalized slot content#

Recipe: Tracking user behavior for personalization#

Recipe: Updating Context on route changes (React Router)#

In a client-side SPA with React Router, Uniform Context needs to be told about route changes so signals based on URL patterns can evaluate correctly. Update Context in a useEffect that depends on the current location:

Place this component just below UniformContext in your tree so all child routes benefit from the updated Context state.

Recipe: Displaying visitor scores and quirks for debugging#

Build a debug panel that shows the current visitor's scores and quirks during development. This is useful for verifying that signals fire correctly and enrichments accumulate as expected:

Recipe: DevTools integration#

Enable the Uniform Context DevTools browser extension for debugging:

The DevTools extension lets you inspect and modify visitor scores and quirks in real time during development.

Best practices#

1. Always wrap with UniformContext -- Place the UniformContext provider above UniformComposition in the component tree. Canvas components need Context for personalization, A/B testing, and behavior tracking.

2. Create the Context instance once -- Instantiate the Context object at the module level or in a top-level component, not inside render functions. Creating it in a render function resets visitor state on every render.

3. Use DefaultNotImplementedComponent as fallback -- Always return a fallback from your component resolver. It shows the component type name and a helpful code snippet during development.

4. Mark parameter types as optional -- Even required parameters can be undefined at runtime (e.g., when first adding a component to a composition). Always handle undefined values.

5. Use UniformText and UniformRichText for visible text -- These components provide inline editing support in the Uniform visual editor. Use raw parameter access only for non-visible values like URLs, booleans, or conditional logic.

6. Hydrate composition data for SSR -- When server-rendering, serialize the composition to a <script> tag and read it on the client to avoid re-fetching during hydration.

7. Keep the manifest up to date -- Run npx uniform context manifest publish after modifying signals, enrichments, or quirks. Then re-download or re-fetch the manifest.

8. Use useScores and useQuirks for reactive data -- Accessing context.scores directly does not trigger re-renders. Always use the hooks for values that affect the UI.

9. Avoid tracking inside Personalize -- The Track and TrackFragment components automatically skip tracking when inside a Personalize component to prevent double-counting.

10. Leverage immer for visibility rules -- The useClientConditionsComposition hook requires immer >= 10 as a peer dependency. Install it if you use client-side visibility rules.