Claritype Embed

Getting started

This page takes you from npm install to a working Claritype sidebar with an open/close button. It assumes you have the origin URL that serves your embedded components, which Claritype provides for your integration.

Install

npm install @claritype/embed-react

React 18+ and react-dom are peer dependencies; you almost certainly have them already.

1. Wrap your app in the provider

<ClaritypeProvider> holds your integration’s identity and shared configuration. All parts of your app that provide context to Claritype and receive actions from it must be within a single ClaritypeProvider:

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

export function App() {
  return (
    <ClaritypeProvider
      origin="https://claritype.acme.example" // provided by Claritype
    >
      <YourApp />
    </ClaritypeProvider>
  );
}

origin is the only required prop. Claritype resolves the organization from the signed-in user and loads that organization’s default project, so your build carries no Claritype identifiers. To load a different project, pass project; to choose among several organizations the user belongs to, pass orgId together with project. Naming an organization selects among those the user can already reach; it never grants access to one.

orgId, project, and origin are fixed while the provider is enabled. There’s nothing to await — rendering the provider is cheap and synchronous.

Single sign-on

If your users sign in to your app with an identity provider that Claritype federates — rather than having Claritype logins of their own — add the connection name Claritype gave you for your integration:

<ClaritypeProvider
  origin="https://claritype.acme.example"
  connection="acme-sso" // provided by Claritype
>

If you set connection, the component shows users a “Sign in” button when it is first opened. If the user still has an active session with the identity provider, the user is taken directly to the assistant. If not, the identity provider login appears in a popup window. The assistant appears once the user has successfully logged in.

If you provide a connection name that isn’t available on the Claritype side, the component shows an error and diagnostic information is logged to the browser console to help you resolve the issue.

When connection isn’t specified, the component displays a standard Claritype login page which asks the user to choose a method to log in to their Claritype account.

2. Place a surface

A surface is a spot in your layout where an embedded Claritype component renders. <ClaritypeSurface> renders a container and fills it with the component; you size and position that container like any other element, via className or style.

The one component available today is the sidebar:

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

<aside className="claritype-panel">
  <ClaritypeSurface component={Component.Sidebar} className="fill" />
</aside>;

.claritype-panel {
  width: 400px;
}
.fill {
  height: 100%;
}

The surface fills whatever box you give it, so make sure the container has a real width and height — a zero-height div renders a zero-height assistant.

3. Wire up open and close

You may not want the Claritype sidebar open all the time. Your app can hide and show it as needed. Here’s how to wire it up so that Claritype knows when it’s visible and can make it visible when the user calls for it:

You own visibility. The SDK never touches your layout. Opening and closing is you expanding or collapsing the container, however your app does that — a CSS class, a grid track, a drawer component.
Keep the surface mounted. Hide the container with CSS (collapse its width, display: none, …) rather than conditionally rendering the surface. Unmounting it reloads the embedded component and interrupts an in-progress conversation.

Drive the surface’s revealed prop from your open state so the component knows when it’s visible, and pass onReveal so the SDK can ask you to open the panel when something (like a discuss call) needs it shown:

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

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

  return (
    <div className="app-grid">
      <main>
        <button onClick={() => setOpen((o) => !o)}>{open ? "Close" : "Open"} assistant</button>
        {/* ...your app... */}
      </main>

      {/* The track collapses; the surface inside stays mounted. */}
      <aside className={open ? "ct-track open" : "ct-track"}>
        <ClaritypeSurface
          component={Component.Sidebar}
          className="fill"
          revealed={open}
          onReveal={() => setOpen(true)}
        />
      </aside>
    </div>
  );
}

.ct-track {
  width: 0;
  overflow: hidden;
  transition: width 0.2s ease;
}
.ct-track.open {
  width: 400px;
}

That’s a complete minimal integration: your users can open the sidebar and start a conversation.

4. Check that it’s working

Pass debug on the provider while you’re developing:

<ClaritypeProvider origin="…" debug>

With debug on, the SDK logs its traffic to the console and warns about common integration mistakes (like a surface’s container being removed from the DOM). You can also hook the lifecycle directly:

<ClaritypeSurface
  component={Component.Sidebar}
  onReady={() => console.log("Claritype is live")}
  onHandshakeFailed={(failure) => console.error("Claritype failed:", failure.code)}
/>

onReady fires once the component has connected. onHandshakeFailed means the component can’t serve this session (wrong org or project, or the user isn’t authorized) — see Components for the failure codes.

Using the assistant conditionally

Apps may show Claritype only to some users: behind a feature flag, an entitlement, or a sign-in. Don’t render the provider conditionally — pass your gate as enabled and keep everything else in place:

<ClaritypeProvider
  enabled={aiChatFlag && isEntitled && !!origin}
  origin={origin}
  connection={connection}
>
  <App /> {/* tree shape never changes */}
  <aside className={open ? "open" : ""}>
    <ClaritypeSurface
      component={Component.Sidebar}
      discussTarget
      revealed={open}
      onReveal={() => setOpen(true)}
    />
  </aside>
</ClaritypeProvider>

While enabled is false, nothing connects to Claritype and origin may be empty. Your pages can still call useClaritypeContextSource and useClaritype() unconditionally; read useClaritype().enabled to hide your own Claritype affordances, such as the button that opens the sidebar. See Components for the details.

Next steps

Tell the assistant what the user is looking at: Passive context
Add “Explain this” affordances to your UI: Discuss
Let the assistant act in your app: Actions
Full props reference for the provider and surface: Components

Using plain JavaScript?

The SDK is written in TypeScript but works identically from JavaScript — every example in these docs works with the type annotations removed. A few notes:

Component is a regular runtime value, not just a type, so component={Component.Sidebar} works as-is in JavaScript. The string "sidebar" is equivalent if you prefer it.
Action handler parameters arrive as plain objects. In TypeScript you’d annotate them; in JavaScript just destructure what you expect. Parameters are validated against your project’s schema before they reach your handler either way.
Everything else — props, hooks, return values — is the same.

The JSX above compiles with any standard setup (Vite, Next.js, Babel); no TypeScript toolchain required.