Claritype Embed

Components

The SDK has two components. <ClaritypeProvider> configures your integration once for the whole app; <ClaritypeSurface> places one embedded Claritype component into your layout. This page is the full reference for both.

<ClaritypeProvider>

Wrap your app (or at least everything that uses Claritype) in a single provider. It establishes your integration’s identity, holds the shared action handlers, and makes the hooks and surfaces below it work.

import { ClaritypeProvider } from "@claritype/embed-react";

<ClaritypeProvider
  orgId="acme"
  project="sales"
  origin="https://claritype.acme.example"
  themeMode={colorMode}
  handlers={handlers}
>
  <YourApp />
</ClaritypeProvider>;

Props

Prop	Type	Required	Description
orgId	string	yes	Your Claritype organization ID. Fixed for the provider’s lifetime.
project	string	yes	Your Claritype project ID. Fixed for the provider’s lifetime.
origin	string	yes	The origin that serves your embedded components, provided by Claritype for your integration. A bare http(s) origin like https://claritype.acme.example — a path, query, fragment, or credentials throws at mount. Fixed for the provider’s lifetime.
handlers	ActionRegistry	no	Action handlers the assistant can invoke. See Actions.
themeMode	"light" \| "dark"	no	Your app’s current color mode. Defaults to "light". Updates apply live.
debug	boolean	no	Log SDK diagnostics and integration warnings to the console. Defaults to false.

Behavior and lifecycle

• One provider per app. The provider represents your integration’s session. Mount it where it will stay mounted and contain all state- and action-bearing components.
• Identity is fixed. orgId, project, and origin are read when the provider mounts. To point at a different project, remount the provider (e.g. with a key), which starts a fresh session.
• themeMode is live. It’s the one prop designed to change over time — bind it to your app’s color mode and every surface follows along. The look of the embedded component (colors, fonts) is configured in your Claritype project; at runtime this allows switching between light and dark variants.
• Handlers don’t need memoizing. You can pass a fresh handlers object every render; handler bodies always see your latest props and state. The set of action keys and versions, though, is fixed at mount — see Actions.
• StrictMode-safe. React’s development-mode double mounting won’t reload the embedded component or reset any state.
• SSR-safe. Rendering the provider on the server is fine; it touches no browser APIs until surfaces mount on the client. The package ships a "use client" directive for Next.js App Router.

<ClaritypeSurface>

A surface is one embedded Claritype component living wherever you choose in your layout. <ClaritypeSurface> renders a container <div> and mounts the component into it using an <iframe>. Use it anywhere within the provider.

import { ClaritypeSurface, Component } from "@claritype/embed-react";

<ClaritypeSurface
  component={Component.Sidebar}
  discussTarget
  revealed={open}
  onReveal={() => setOpen(true)}
  className="fill"
/>;

Props

Prop	Type	Required	Description
component	Claritype SDK Component (see below)	yes	Which embedded component this surface renders. Fixed for the surface’s lifetime.
discussTarget	boolean	no	Make this the surface that discuss() routes to. Fixed for the surface’s lifetime. If omitted from all surfaces, routing is automatic.
revealed	boolean	no	Declaratively drive this surface’s visibility (see below).
onReveal	() => void \| Promise<void>	no	Called when the SDK needs this surface visible — open your panel here (see below).
onReady	() => void	no	Called once, when the component has connected and the session is live.
onHandshakeFailed	(failure: HandshakeFailedPayload) => void	no	Called if the component can’t serve this session. Ends this surface’s lifecycle.
frameUrl	string	no	Full component URL override, for local development and testing. Takes precedence over the provider’s origin. Fixed for the surface’s lifetime.
className	string	no	Class for the container <div>. Use to size and position the surface.
style	CSSProperties	no	Inline styles for the container <div>.

Available components

Component enumerates the embedded components Claritype serves:

Value	String form	Description
Component.Sidebar	"sidebar"	The conversational sidebar.

More components will be added over time.

Sizing

The embedded component fills the container <div> completely; the SDK never positions or floats anything. Give the container real dimensions via className/style (or its parent’s layout) — the surface is exactly as big as the box you give it.

Keep surfaces mounted

The most important rule of surface lifecycle: hide, don’t unmount. When a surface unmounts, the embedded component is torn down, and remounting it later starts it from scratch — the in-progress conversation state is dropped. So:

// ✅ Keep it mounted; hide the container.
<aside hidden={!open}>
  <ClaritypeSurface component={Component.Sidebar} revealed={open} … />
</aside>

// ❌ Don't conditionally render it.
{open && <ClaritypeSurface component={Component.Sidebar} … />}

The same applies to tab libraries and routers: use their keepMounted / forceMount options for the panel a surface lives in. With debug on, the SDK warns in the console when it detects a surface’s container leaving the DOM.

Ordinary re-renders of your tree are fine — only a real unmount (or a remount caused by a changed key) resets the surface. React StrictMode’s double-invoke in development is absorbed and won’t reload anything.

Visibility: revealed and onReveal

Your app owns whether a surface is visible; the SDK just needs to be kept in the loop (so the component can, say, pause work while hidden), and asks you to show the surface when the user calls for it within your app. Two props cover this:

• revealed — declarative visibility. Bind it to the same state that shows/hides the container, and the SDK tells the component whenever the value changes. It’s replayed automatically when the component (re)connects, so a surface that starts open, or reloads, comes up in sync. If you never pass revealed, the SDK simply doesn’t track visibility for you.
• onReveal — A callback that fires when the SDK wants to show the surface. In practice that’s a discuss() call, which implies opening the panel. Do whatever your layout needs, e.g. set your open state or switch to the right tab. It may be async. Make it idempotent, as it can fire while the surface is already visible.

Here’s an example using onReveal and revealed when they apply to the same state:

const [open, setOpen] = useState(false);

<ClaritypeSurface
  component={Component.Sidebar}
  discussTarget
  revealed={open} // your state drives the component's visibility…
  onReveal={() => setOpen(true)} // …and discuss can open the panel
/>;

Handshake callbacks

When a surface mounts, the embedded component loads and connects to the SDK — the handshake. Two callbacks report how that goes:

• onReady fires once, when the handshake completes and the session is live. Useful for logging or deferring UI that depends on the assistant. For a reactive “is it ready” value you can render against, use useClaritype().canDiscuss instead.
• onHandshakeFailed fires if the component reports it cannot serve this session. This is final for the surface. The failure has a code and a human-readable message (diagnostic; not necessarily suitable to show end users verbatim):

code	Meaning
"context_missing"	The org/project couldn’t be determined from the surface’s URL.
"not_found"	The org or project doesn’t exist.
"unauthorized"	The current user isn’t allowed to access this project.
"unknown"	Anything else.

A failed surface is a good place to fall back gracefully — hide the panel and the affordances that open it. If the Claritype origin is unreachable altogether, the surface simply never becomes ready: no errors propagate into your app, and canDiscuss stays false, which is your signal to keep Claritype affordances hidden.

frameUrl

frameUrl overrides the URL the surface loads, verbatim. Normally the SDK derives it from the provider’s origin plus your org, project, and the component; frameUrl bypasses that entirely. You’d use it to point a surface at a local or staging deployment during development. Like component, it’s read once at mount.