@holectus/react

Embeddable React UI for Holectus document collection (subjects) and admin review.

Talks to the hosted Holectus API. You create an API key in the dashboard, mint short-lived access tokens on your server, and mount the components in your app.

Install

npm install @holectus/react @holectus/core @holectus/next

Peer dependencies: react and react-dom ^19.

Quickstart (hosted API)

1. Sign up at the Holectus dashboard and create an API key (subject and/or admin scope).
2. Set server-only env vars (never NEXT_PUBLIC_ for the key):
   • HOLECTUS_API_URL — your Holectus API origin
   • HOLECTUS_API_KEY — dashboard API key
3. Add a session route with createHolectusSessionRoute from @holectus/next.
4. Import styles once and mount with tokenEndpoint:

import { DocumentChecklist } from '@holectus/react';
import '@holectus/react/styles.css'; // once in your app (e.g. root layout)

export function SubjectDocuments({ subjectId }: { subjectId: string }) {
  return (
    <DocumentChecklist
      tokenEndpoint={`/api/holectus/session?subjectId=${encodeURIComponent(subjectId)}`}
    />
  );
}

Admin flows use DocumentManager with an admin session route (assertAuthorized on the server).

Full walkthrough: Quickstart · Next.js

Advanced (headless client)

Prefer tokenEndpoint unless you need a custom client. If you build one yourself, mint the subject access token on your server and pass it in — never ship HOLECTUS_API_KEY to the browser.

import { DocumentChecklist, createHttpDocumentChecklistClient } from '@holectus/react';

const client = createHttpDocumentChecklistClient({
  baseUrl: process.env.NEXT_PUBLIC_HOLECTUS_API_URL!, // API origin only
  token: subjectAccessTokenFromYourServer,
});

<DocumentChecklist subjectId={subjectId} client={client} />;

Styling

Import @holectus/react/styles.css once in your app. Rules are scoped under .holectus-root so they do not leak into your UI.

Override brand tokens on :root or .holectus-root:

.holectus-root {
  --holectus-brand-accent: #4f46e5;
  --holectus-brand-accent-hover: #4338ca;
}

Pass className on DocumentChecklist / DocumentManager to scope overrides to one embed. Dark mode follows a .dark ancestor. Optional presets: @holectus/react/themes.css + data-holectus-theme.

Components

| Export | Role | |--------|------| | DocumentChecklist | Subject checklist and uploads | | createHttpDocumentChecklistClient | fetch client for status + upload | | DocumentManager | Subjects, slots, expiring docs, review | | createHttpDocumentManagerClient | Admin API client | | useHolectusSession | Hook for custom tokenEndpoint wiring |

Upload strategies

DocumentChecklist accepts uploadStrategy: 'proxy' | 'direct' | 'auto' (default 'auto'). The HTTP client intersects your preference with GET /api/documents/upload-capabilities. Direct uploads use a presigned PUT when the file is at least directUploadMinBytes (default 4 MiB).

Docs

• SDK — @holectus/react
• Document checklist
• Document manager