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 your three integration values from Claritype: an organization ID, a project ID, and the origin URL that serves your embedded components.

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
      orgId="acme"
      project="sales"
      origin="https://claritype.acme.example" // provided by Claritype
    >
      <YourApp />
    </ClaritypeProvider>
  );
}

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

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 orgId="acme" project="sales" 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.

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.