\| undefined` | Dynamic input values from route parameters |
| `resolveRenderer` | `RenderComponentResolver \| undefined` | The active component resolver |
| `behaviorTracking` | `'onLoad' \| 'onView' \| undefined` | The behavior tracking mode |
#### useUniformCurrentComponent
Returns the data from the nearest `UniformComponent` ancestor (the currently rendering component):
```tsx
import { useUniformCurrentComponent } from "@uniformdev/canvas-react";
const DebugInfo = () => {
const { data } = useUniformCurrentComponent();
if (!data) return null;
return (
Type: {data.type}
{"\n"}Parameters: {JSON.stringify(data.parameters, null, 2)}
);
};
```
#### 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:
```tsx
import {
UniformComposition,
useUniformContextualEditing,
} from "@uniformdev/canvas-react";
function PreviewPage({ initialComposition }) {
const { composition, isContextualEditing } = useUniformContextualEditing({
initialCompositionValue: initialComposition,
enhance: async (composition) => {
// Optional: run enhancers on the composition before rendering
return composition;
},
});
return (
);
}
```
| Property | Type | Description |
| --- | --- | --- |
| `composition` | `RootComponentInstance` | The current composition data (updates live during editing) |
| `isContextualEditing` | `boolean` | `true` when the Uniform editor is active |
> **Note:**
>
> Contextual editing is automatically set up when you use `UniformComposition` with the `contextualEditingEnhancer` prop. Use `useUniformContextualEditing` directly only when you need full control over the editing lifecycle.
#### useUniformContextualEditingState
Provides information about the current contextual editing state, such as which component is selected in the editor:
```tsx
import { useUniformContextualEditingState } from "@uniformdev/canvas-react";
const ComponentHighlight = ({ children }) => {
const { isContextualEditing, selectedComponentReference, previewMode } =
useUniformContextualEditingState();
const isSelected =
selectedComponentReference?.componentId === component._id;
return (
{children}
{previewMode === "editor" && (
Editor mode
)}
);
};
```
| Property | Type | Description |
| --- | --- | --- |
| `isContextualEditing` | `boolean` | Whether contextual editing is active |
| `selectedComponentReference` | `object \| undefined` | Reference to the currently selected component in the editor |
| `previewMode` | `'editor' \| 'preview' \| undefined` | The current preview mode |
#### useClientConditionsComposition
Evaluates client-side visibility rules on a composition and returns a filtered composition with invisible components removed:
```tsx
import { useClientConditionsComposition } from "@uniformdev/canvas-react";
function PageWithVisibility({ composition }) {
// Evaluates quirk-based visibility rules on the client
const filteredComposition = useClientConditionsComposition(composition);
return (
);
}
```
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`:
```tsx
{
// Optional: apply data enhancers or transformations
return composition;
}}
/>
```
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](https://github.com/uniformdev/examples/tree/main/examples/react-vite-ssr) starter):
```js
// server.js
import express from "express";
import cors from "cors";
import {
isAllowedReferrer,
EMPTY_COMPOSITION,
IN_CONTEXT_EDITOR_CONFIG_CHECK_QUERY_STRING_PARAM,
} from "@uniformdev/canvas";
import { getComposition } from "./src/uniform/api.js";
const app = express();
// CORS is required so the Uniform dashboard can load your app in an iframe
app.use(cors());
app.use("*", async (req, res) => {
// 1. Config check: the editor pings this to detect capabilities
const isConfigCheck =
req.query[IN_CONTEXT_EDITOR_CONFIG_CHECK_QUERY_STRING_PARAM] === "true";
if (isConfigCheck) {
res.json({ hasPlayground: true });
return;
}
// 2. Preview mode: when loaded inside the Uniform visual editor
let composition;
if (
req.params[0] === "/api/preview" &&
isAllowedReferrer(req.headers.referer)
) {
// No need to fetch -- the editor sends composition data via postMessage.
// Use the empty stub so the page can render and establish the channel.
composition = EMPTY_COMPOSITION;
} else {
// Normal request: fetch the composition from Uniform
composition = await getComposition(req.params[0]);
}
// Server-render the app with the composition data
const rendered = await render({ composition });
const html = template
.replace("", rendered.html ?? "");
res.status(200).set({ "Content-Type": "text/html" }).send(html);
});
```
> **Note:**
>
> `isAllowedReferrer` checks that the request originates from the Uniform dashboard domain. `EMPTY_COMPOSITION` is a minimal valid composition stub that lets the page render before the editor injects the real data. Both are exported from `@uniformdev/canvas`.
#### 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](https://github.com/uniformdev/examples/tree/main/examples/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:
```tsx
import { UniformPlayground } from "@uniformdev/canvas-react";
function PlaygroundPage() {
return (
);
}
```
---
## 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](https://github.com/uniformdev/examples/tree/main/examples/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.
```tsx
// App.tsx -- Context-only setup with React Router
import { UniformContext, useUniformContext } from "@uniformdev/context-react";
import { createUniformContext } from "./uniform/uniformContext";
import { Routes, Route, useLocation } from "react-router-dom";
import { useEffect } from "react";
import { parse } from "cookie";
const clientContext = createUniformContext();
function App() {
return (
);
}
function AppRoutes() {
const { context } = useUniformContext();
const location = useLocation();
// Update Context on every route change with current URL and cookies
useEffect(() => {
context.update({
url: new URL(
`${document.location.protocol}//${document.location.host}${location.pathname}${location.search}`
),
cookies: parse(document.cookie ?? ""),
});
}, [location, context]);
return (
} />
} />
} />
);
}
```
In this pattern, you track enrichments programmatically inside your page components:
```tsx
// DevelopersPage.tsx
import { useUniformContext } from "@uniformdev/context-react";
import { useEffect } from "react";
export default function DevelopersPage() {
const { context } = useUniformContext();
useEffect(() => {
context.update({
enrichments: [
{
cat: "audience",
key: "dev",
str: 10,
},
],
});
}, [context]);
return For Developers
;
}
```
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:
```tsx
import { Context, ManifestV2 } from "@uniformdev/context";
import { UniformContext } from "@uniformdev/context-react";
// The manifest defines your signals, enrichments, quirks, and tests.
// In production, fetch this from the Uniform API or embed it at build time.
const manifest: ManifestV2 = {
project: {
pz: {
sig: {
// Signal definitions
},
},
test: {
// A/B test definitions
},
},
};
const context = new Context({
manifest,
defaultConsent: true,
});
function App({ children }) {
return (
{children}
);
}
```
#### 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:
```tsx
import {
Context,
CookieTransitionDataStore,
} from "@uniformdev/context";
const context = new Context({
manifest,
defaultConsent: true,
transitionStore: new CookieTransitionDataStore({
// For SSR, pass the cookie value from the server request headers:
serverCookieValue: serverCookieValue ?? "",
}),
});
```
> **Tip:**
>
> For SSR apps, read the `ufvd` cookie from the incoming request headers and pass it as `serverCookieValue`. This ensures the server-rendered HTML reflects the visitor's existing scores and quirks.
#### Enabling debug logging
Use `enableDebugConsoleLogDrain` during development to log all Context activity (signal evaluations, score changes, enrichment tracking) to the browser console:
```tsx
import {
Context,
enableContextDevTools,
enableDebugConsoleLogDrain,
} from "@uniformdev/context";
const context = new Context({
manifest,
defaultConsent: true,
plugins: [
enableContextDevTools(),
enableDebugConsoleLogDrain("debug"),
],
});
```
#### UniformContext props
| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `context` | `Context` | Yes | A configured Uniform Context instance |
| `outputType` | `'standard' \| 'edge'` | No | Rendering mode (default: `'standard'`). Use `'edge'` for edge-side personalization |
| `trackRouteOnRender` | `boolean` | No | Whether to track route changes on render (default: `true`) |
| `includeTransferState` | `'always' \| 'never' \| 'server-only'` | No | When to include server-to-client state transfer for SSR hydration (default: `'server-only'`) |
#### Transfer state for SSR
When server-rendering, the `UniformContext` automatically injects a `