Skip to main content
The @clinikapi/react package gives you nine production-ready clinical UI widgets you can embed directly in your React application. Every widget communicates with ClinikAPI through a backend proxy you control — your secret API key never touches the browser. Install the package, expose one API route per widget, and you have a full clinical interface in minutes.

​
Installation

npm install @clinikapi/react

​
The proxy pattern

Widgets run in the browser and cannot use the @clinikapi/sdk directly — doing so would expose your secret API key to anyone who inspects network traffic. Instead, each widget accepts a proxyUrl prop pointing to an API route on your own backend. Your backend holds the key, calls ClinikAPI, and returns the data. 
Browser widget → Your backend proxy → ClinikAPI SDK → ClinikAPI
Never import @clinikapi/sdk in client-side code. The SDK is server-side only. Use @clinikapi/react with a backend proxy for all frontend UI.
This design means you retain full control over authentication and authorization. Your proxy can check session tokens, enforce row-level permissions, or apply any other business logic before forwarding requests to ClinikAPI.

​
Setting up a backend proxy

The following example shows a Next.js App Router API route that powers the PatientDashboard widget. The pattern is the same for every other widget — the only thing that changes is which SDK method you call. 
// app/api/clinik/patients/[id]/route.ts
import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const { data } = await clinik.patients.read(params.id, {
    include: ['Encounter', 'Observation', 'MedicationRequest', 'Appointment'],
  });

  return Response.json(data);
}
Store your key as CLINIKAPI_SECRET_KEY in your environment variables. Use a clk_test_* key during development so you work against the isolated test datastore, not production data.

​
Using a widget

Once your proxy route is in place, import the widget and pass it the proxy URL: 
import { PatientDashboard } from '@clinikapi/react';

export default function PatientPage({ patientId }: { patientId: string }) {
  return (
    <PatientDashboard
      proxyUrl={`/api/clinik/patients/${patientId}`}
      onError={(err) => console.error('Dashboard error:', err)}
    />
  );
}

​
Available widgets

WidgetDescription
PatientDashboardFull patient overview with encounters, vitals, and medications
AppointmentSchedulerBook and manage patient appointments
PrescriptionFormCreate and edit medication prescriptions
NoteEditorRich clinical note editor with note type selection
IntakeFormDynamic patient intake questionnaire
ConsentManagerConsent document signing and management
VitalsWidgetVital signs display with trend charts
LabResultsWidgetLab report viewer with result interpretation
PrescriptionWidgetPrescription list and detail viewer

​
Common props

Every widget accepts the following props:
​
props.proxyUrl
string
required
The URL of your backend proxy endpoint. The widget sends all requests to this URL. Must be a same-origin path (e.g. /api/clinik/patients/123) to prevent open redirect attacks.
​
props.className
string
A CSS class name applied to the widget’s root element. Use this to control sizing, spacing, or theming.
​
props.onError
(error: Error) => void
A callback invoked when the widget encounters an error fetching or submitting data. Use this to display error toasts, log to your error tracker, or redirect the user.

​
Security

The proxy pattern enforces a strict security boundary:
  • No key exposure: Widgets never receive or store your ClinikAPI API key.
  • You control access: Your proxy can verify the logged-in user’s session before forwarding any request to ClinikAPI.
  • Open redirect protection: The proxyUrl prop is validated to be a same-origin path — widgets will not follow redirects to external hosts.
  • Tenant isolation: ClinikAPI automatically tags every resource with your organization’s tenant ID, so data from other tenants is never returned regardless of what your proxy requests.
ClinikAPI does not handle end-user authentication. Your backend is responsible for authenticating the user before your proxy calls ClinikAPI. See Authentication for the full auth model.