React

@qirtaas/react wraps @qirtaas/core’s mount API in two components: <QirtaasEditor> and <QirtaasRenderer>. The editor itself is a self-contained island that core bundles in — your React app does not need Vue installed, and only React is a peer dependency.

npm install @qirtaas/react

QirtaasEditor

import { useRef } from "react";
import { QirtaasEditor, type QirtaasEditorHandle } from "@qirtaas/react";

function Compose({ docId }: { docId?: string }) {
  const editor = useRef<QirtaasEditorHandle>(null);

  return (
    <div style={{ height: "70vh" }}>
      <QirtaasEditor
        ref={editor}
        documentId={docId}
        getToken={fetchEmbedToken}
        locale="ar"
        theme="light"
        onDocumentCreated={(id) => saveIdSomewhere(id)}
        onSaveStateChange={(state) => setBadge(state)}
      />
    </div>
  );
}

The editor owns an internal scroll view (pinned toolbar, scrolling body) and fills its container — the parent element must give it a bounded height (e.g. a sized dialog body or h-[60vh]).

Props

Props mirror EditorMountOptions, plus the connection config (the wrapper creates its client internally):

() => Promise<string> | string

required

Returns a short-lived embed token. Called on init, before expiry, and on 401. See Authentication.

string

default:"https://api.qirtaas.io"

Qirtaas API base URL.

string

Existing document to load. Omit to lazy-create on first edit (onDocumentCreated delivers the new id).

Json | null

Initial content (TipTap JSON) when not loading from a documentId.

"en" | "ar"

"light" | "dark"

boolean

default:"false"

boolean

AutosaveOptions

See Types. Set { enabled: false } and call save() on the ref to drive persistence yourself.

Callback props (onReady, onChange, onSaveStateChange, onDocumentCreated, onError, onTokenExpired, onEvent) match the editor callbacks one-to-one. Always the latest render’s callbacks are invoked — capturing state in them is safe.

Live updates vs. remount

The component mounts the editor once. Only two props are live after mount:

theme — forwarded to setTheme
readOnly — forwarded to setEditable

Changing anything else (documentId, getToken, locale, …) requires a remount — give the component a key that changes with them:

<QirtaasEditor key={docId} documentId={docId} getToken={getToken} />

The mount effect is StrictMode-safe: the dev-mode double invoke fully tears down and cleanly re-mounts.

Ref handle (`QirtaasEditorHandle`)

Json | null

Current editor content (TipTap JSON).

Promise<void>

Force an immediate save of pending changes.

void

QirtaasRenderer

Read-only display. Supply exactly one auth source — shareToken, getToken, or getSignature (see Renderer auth modes).

import { QirtaasRenderer } from "@qirtaas/react";

<QirtaasRenderer
  documentId={docId}
  getSignature={() => fetchSignature(docId)} // cross-user read
  locale="ar"
  theme="light"
  onError={(code) => report(code)}
/>

Props

string

default:"https://api.qirtaas.io"

string

Document to render. With shareToken, the token resolves the document.

Public read.

() => Promise<string> | string

Own-document read (embed token).

() => Promise<{ signature: string; exp: number }>

Cross-user read (per-document HMAC signature).

"en" | "ar"

"light" | "dark"

Callbacks: onReady, onError. Ref handle (QirtaasRendererHandle) exposes setTheme(theme). As with the editor, only theme is live — remount (via key) for anything else.

Imperative client operations

For mount-less operations (e.g. driving a document list view), the package re-exports the client:

import { createQirtaasClient } from "@qirtaas/react";

const qirtaas = createQirtaasClient({ getToken: fetchEmbedToken });
const docs = await qirtaas.listDocuments(); // [{ id, title, … }]
await qirtaas.deleteDocument(id);

Get started

Tutorials

SDK

Auth

Self-hosting

AI

QirtaasEditor

Props

Live updates vs. remount

Ref handle (`QirtaasEditorHandle`)

QirtaasRenderer

Props

Imperative client operations

​QirtaasEditor

​Props

​Live updates vs. remount

​Ref handle (QirtaasEditorHandle)

​QirtaasRenderer

​Props

​Imperative client operations

QirtaasEditor

Props

Live updates vs. remount

Ref handle (`QirtaasEditorHandle`)

QirtaasRenderer

Props

Imperative client operations