Components

React

Add a complete connected billing workspace or compose submission, search, reporting, and lifecycle surfaces individually.

Add billing to your application

Install the package; components include their own styles. First connect an authenticated server session route; the examples below assume that route is ready.

pnpm add @mindbill/react@0.73.0

Billing page: ConnectedBillingWorkspace provides task queues, All Bills, reports, bill details, and a Settings tab.
Case billing tab: BillSubmissionForm before submission; ConnectedBillLifecycle afterward.
Billing settings: use the built-in Settings tab, or mount BillingSettings separately. The server requires an admin-authorized session.

Example: place components in your existing routes

"use client";
import {
  ConnectedBillingWorkspace, ConnectedBillLifecycle,
  BillSubmissionForm, BillingSettings, type BillSubmissionFormProps,
} from "@mindbill/react";

// Sidebar -> /billing. The workspace owns bill selection and detail navigation.
export function BillingPage({ canManageBilling }: { canManageBilling: boolean }) {
  return <ConnectedBillingWorkspace
    sessionEndpoint="/api/mindbill/session"
    showSettings={canManageBilling}
    billingSettings={{ sessionEndpoint: "/api/mindbill/settings-session" }}
    style={{ height: "calc(100dvh - 96px)", minHeight: 0 }}
    onCreateBill={() => { window.location.href = "/billing/new"; }}
  />;
}

// Case -> Billing tab after Report. Host server authorizes the case and resolves
// its saved bill ID; return a bill-scoped session from this separate host route.
export function CaseBilling({ caseId, billId }: { caseId: string; billId: string }) {
  return <ConnectedBillLifecycle billId={billId}
    sessionEndpoint={"/api/cases/" + encodeURIComponent(caseId) + "/billing-session"} />;
}

// Map existing structured case data to BillSubmissionInput, persist result.billId
// using your existing case metadata/API, and keep unknown fields editable.
export function NewBill({ canManageBilling, ...billProps }: Pick<
  BillSubmissionFormProps, "initialBill" | "attachments" | "onSubmitted"
> & { canManageBilling: boolean }) {
  return <BillSubmissionForm {...billProps}
    {...(canManageBilling ? { billingSettings: {
      sessionEndpoint: "/api/mindbill/settings-session"
    } } : {})}
    sessionEndpoint="/api/mindbill/session" />;
}

// Optional standalone settings page; the workspace already has a Settings tab.
// This administrator-only endpoint grants organization:manage.
export function PracticeBillingSettings() {
  return <BillingSettings sessionEndpoint="/api/mindbill/settings-session" />;
}

Keep the returned billId in your existing case metadata. Send your case ID as externalId for correlation; it is not a uniqueness guarantee. Never create a bill on component mount.

Give the workspace a bounded height and min-height: 0 in flex ancestors when your app disables page scrolling.

Component catalog

All React exports and when to use them

ExportUse it whenOwns API calls

FeeScheduleCalculatorCalculate multiple California treatment lines with modifiers, sources, and coding review. Integration guide.Through your reference client

BillSubmissionFormYou want the complete form, reference data, validation, attachments, and atomic Submit action.Yes

ReportAutofillReview optional, capability-gated PDF suggestions before applying them to empty fields.Yes, or through your adapter

BillSubmission*SectionYou want the same component-owned form state with individually composable sections.Yes, through the parent

ConnectedBillingWorkspaceYou want Bill Tasks, All Bills, reports, settings, and per-bill lifecycle in one integrated surface.Yes

ConnectedBillSearchYou need the authoritative bill registry with patient, bill, claim, status, and A/R filters.Yes

ConnectedBillTasksDashboardYou need actionable billing queues grouped by task and age.Yes

ConnectedServiceLineItemsReportYou need original submissions grouped by procedure code.Yes

ConnectedProductivityReportYou need created, transmitted, submitted, and acceptance performance by biller.Yes

BillingDashboardYou need receivables KPIs, aging buckets, search, filters, and a responsive bill list, plus optional settings.Settings only

BillListYou need only the searchable and filterable bill directory.No

BillAgingSummaryYou need only receivables and aging KPIs.No

BillingReportYou need grouped status, payer, or aging reporting.No

BillStatusAgingMatrixYou need the status × aging management grid with drill-down cells and totals.No

BillReadOnlyFormYou want the same bill layout after submission without editing.No

ConnectedBillLifecycleYou want the complete post-submission workflow.Yes

useBillLifecycleYou want custom post-submission lifecycle UI.Yes

ConnectedBillStatusYou need compact status and valid next actions.Yes

useBillStatusYou want custom status UI.Yes

BillStatusSummaryYou need a presentational status card.No

BillLifecycleActionsYou need state-aware actions in your own layout.No

BillLifecycleProgressYou need the horizontal bill lifecycle.No

BillSnapshotSummaryYou need a compact submitted CMS-1500 snapshot.No

BillExplanationOfReviewYou need the consolidated EOR, denial, remittance, and payment reconciliation surface.No

BillRemittanceCardYou need payer-reported, posted, and balance amounts.No

BillPayerContactCardYou need payer and adjuster follow-up contacts.No

BillPaymentLedgerYou need posted payment history.No

BillActivityTimelineYou want to render the bill's complete history.No

MindBillBillReviewYou prefer the hosted post-submission review surface.Hosted

MindBillBillTimelineYou prefer the hosted timeline surface.Hosted

Complete submission form

BillSubmissionForm owns which fields exist and which are required. It renders red asterisks, validates the values, resolves billing reference data through a short-lived browser session, lets users review prefilled documents and add uploads, and renders the Submit button. It never creates a MindBill draft.

Submission session permissions

This excerpt assumes your server has authenticated the user, checked membership, and selected the organization credential. See the complete server route for origin checks and error handling.

app.post("/api/mindbill/submission-session", async (req, res) => {
  const user = await requireSignedInUser(req);

  res.json(await mindbill.createBrowserSession({
    subject: user.id,
    permissions: ["bills:create", "payers:read"],
    allowedOrigin: process.env.APP_ORIGIN!,
    expiresIn: 900,
  }));
});

import { BillSubmissionForm } from "@mindbill/react";

<BillSubmissionForm
  initialBill={toBillSnapshot(caseRecord)}
  attachments={selectedBillingDocuments}
  sessionEndpoint="/api/mindbill/submission-session"
  appearance={{ preset: "orange-bright" }}
  submitLabel="Submit bill"
  onSubmitted={({ billId }) => rememberBillId(billId)}
/>

Optionally pass reportAutofill with a separately authorized connection, or use ReportAutofill in a custom form. The report autofill guide covers access, explicit review, and preserving existing values.

Prefill case data and final-report attachments

Map data you already have: patient name, date of birth and address; claim, employer and injury date; service date; diagnosis codes; procedure codes, modifiers and units. Keep missing values editable. Confirm a canonical claims administrator in the payer picker; a text label from a report is not a verified payer ID.

Use your existing structured extraction results, or opt into the capability-gated report autofill component from React 0.67.0. Review suggestions before applying them to empty fields. Do not infer clinical codes or fabricate missing information.

// Host adapter example: rename these source fields to your existing structured data.
// This med-legal adapter omits treatment charges and line-level diagnosis pointers.
// For professional treatment, use /learn/treatment-quickstart.
// Do not infer clinical codes or upload every case document during SDK setup.
export function billFromCase(caseRecord) {
  return {
    externalId: String(caseRecord.id),
    patient: {
      firstName: caseRecord.patient.firstName ?? "",
      lastName: caseRecord.patient.lastName ?? "",
      dateOfBirth: caseRecord.patient.dateOfBirth ?? "", // YYYY-MM-DD
      address: {
        line1: caseRecord.patient.address?.line1 ?? "",
        city: caseRecord.patient.address?.city ?? "",
        state: caseRecord.patient.address?.state ?? "",
        postalCode: caseRecord.patient.address?.postalCode ?? "",
      },
    },
    claim: {
      claimNumber: caseRecord.claimNumber ?? "",
      employer: caseRecord.employerName,
      dateOfInjury: caseRecord.dateOfInjury,
    },
    service: { date: caseRecord.dateOfService ?? "" },
    diagnoses: caseRecord.diagnosisCodes ?? [],
    serviceLines: (caseRecord.billingLines ?? []).map((line) => ({
      code: line.code, modifiers: line.modifiers, units: line.units,
    })),
    // Optional: billingProvider, renderingProvider, serviceLocation from
    // your saved host settings. Otherwise let the user supply/review them.
  };
}

// Only pass the finalized report. An empty list leaves upload to the user.
// documentId identifies a HOST document, not a MindBill document.
export function finalReportSources(documentId) {
  if (!documentId) return [];
  return [{
    id: documentId, fileName: "final-report.pdf",
    documentType: "final_report", autoAttached: true, removable: true,
    loadBlob: async () => {
      // Existing authenticated host endpoint: enforce document/case ownership.
      const response = await fetch("/api/documents/" + encodeURIComponent(documentId), {
        credentials: "same-origin", cache: "no-store",
      });
      if (!response.ok) throw new Error("Unable to load finalized report");
      return response.blob();
    },
  }];
}

Pass billFromCase(caseRecord) as initialBill and finalReportSources(finalizedReportId) as attachments. All supplied source attachments are included unless removed: do not pass every case document or rely on selected: false. Users can add proof of service and other supporting PDFs in the form, including a final report edited outside your app.

BillSubmissionFormSynthetic data · edit and run

import { useState } from "react";
import { BillSubmissionForm } from "@mindbill/react";

const initialBill = {
  externalId: "report_9f7a",
  billingMode: "med_legal",
  patient: {
    externalId: "patient_42", firstName: "Alex", lastName: "Morgan",
    dateOfBirth: "1988-03-05",
    address: { line1: "100 Main St", city: "Fresno", state: "CA", postalCode: "93721" },
  },
  claim: {
    externalId: "claim_17", claimNumber: "WC-44871",
    employer: "Northstar Foods", dateOfInjury: "2025-05-30", injuryState: "CA",
    claimsAdministrator: { name: "Republic Indemnity" },
  },
  service: { date: "2026-08-26" },
  billingProvider: {
    name: "Northstar Evaluations", taxId: "123456789", npi: "1023401122",
    address: { line1: "236 W Mountain St", city: "Pasadena", state: "CA", postalCode: "91103" },
  },
  renderingProvider: {
    name: "Morgan Chen, MD", npi: "1098765432",
    licenseNumber: "A140748", licenseState: "CA",
  },
  serviceLocation: {
    name: "West Covina Exam Office", placeOfServiceCode: "11",
    address: { line1: "1050 West Lakes Dr", city: "West Covina", state: "CA", postalCode: "91790" },
  },
  diagnoses: ["M25.562"],
  serviceLines: [{ code: "ML201", modifiers: ["95"], units: 1, charge: 2015 }],
};

const attachments = [
  { id: "doc_report", fileName: "final-report.pdf", documentType: "final_report", selected: true },
  { id: "doc_pos", fileName: "proof-of-service.pdf", documentType: "proof_of_service", selected: true },
];

export default function App() {
  const [notice, setNotice] = useState("Review the snapshot and payer packet.");
  return <main className="review-demo">
    <p className="notice">{notice}</p>
    <BillSubmissionForm
      initialBill={initialBill}
      attachments={attachments}
      appearance={{ preset: "clinical-blue" }}
      submitLabel="Submit bill"
      onSubmit={async ({ sourceAttachmentIds, uploads }) => {
        setNotice(
          "Ready to submit " + (sourceAttachmentIds.length + uploads.length) + " documents atomically."
        );
      }}
    />
  </main>;
}

Add billing to your application

Component catalog

Complete submission form

Individual form sections

Dashboard, aging, bill list, and reporting

Search and date filters

Organization onboarding

Treatment and authorization requests

Notification settings

Personal preferences

Post-submission setup

Complete post-submission lifecycle

Shared bill detail sections and related records

Custom lifecycle UI

Status surfaces

Lifecycle surfaces

Actions and history

Browser clients

Hosted wrappers

Appearance and utilities