Quick Start

Get up and running with DocCentral in under 5 minutes. This guide walks you through the essential steps to display a PDF document with interactive fields.

Prerequisites

Before starting, make sure you have:

A React 18+ project set up
A DocCentral account with an API key (get one at doccentral.io/register)
Node.js 18 or higher installed

Step 1: Install the SDK

Install the DocCentral React package using your preferred package manager:

npm install @doccentral/react

Step 2: Set Up Environment Variables

Add your DocCentral API key to your environment variables. The SDK requires a valid API key to authenticate with the DocCentral backend.

.env.localbash

# Your DocCentral API key (get it from the dashboard)
NEXT_PUBLIC_DOCCENTRAL_API_KEY=pk_live_your_api_key_here

# Optional: Custom API URL (for self-hosted or staging)
# NEXT_PUBLIC_DOCCENTRAL_API_URL=https://api.doccentral.io

Security Note

Use pk_ (publishable) keys for client-side code. Never exposesk_ (secret) keys in the browser. Secret keys should only be used in server-side code.

Step 3: Add the Provider

Wrap your application (or the part that uses DocCentral components) with theDocCentralProvider. This provider handles authentication and provides context to all child components.

app/providers.tsxtypescript

'use client';

import { DocCentralProvider } from '@doccentral/react';
import { ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  return (
    <DocCentralProvider
      apiKey={process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY!}
      onReady={() => console.log('DocCentral SDK ready')}
      onError={(error) => console.error('DocCentral SDK error:', error)}
    >
      {children}
    </DocCentralProvider>
  );
}

Step 4: Display a Document

Use the PDFViewer component to display a PDF document with interactive form fields. The component handles rendering, field interactions, and submission.

app/documents/[id]/page.tsxtypescript

'use client';

import { PDFViewer } from '@doccentral/react';

interface DocumentPageProps {
  params: { id: string };
}

export default function DocumentPage({ params }: DocumentPageProps) {
  // In a real app, fetch document details from your backend
  const documentId = params.id;
  const documentUrl = `https://api.doccentral.io/documents/${documentId}/download`;

  return (
    <div className="h-screen">
      <PDFViewer
        documentId={documentId}
        documentUrl={documentUrl}
        showToolbar={true}
        editable={true}
        onDocumentLoad={(pages) => {
          console.log(`Document loaded with ${pages.length} pages`);
        }}
        onSubmit={async (payload) => {
          console.log('Document submitted:', payload);
          // Handle successful submission
          alert('Document submitted successfully!');
        }}
        onSubmitError={(error) => {
          console.error('Submission failed:', error);
          alert(`Submission failed: ${error.message}`);
        }}
      />
    </div>
  );
}

Step 5: Test Your Integration

Run your development server and navigate to your document page:

npm run dev

You should see the PDF viewer load with any pre-defined fields. Users can interact with the fields, add signatures, and submit the completed document.

Debug Mode

Enable debug mode to see detailed logs of SDK operations:

<DocCentralProvider apiKey="..." debug={true}>
  ...
</DocCentralProvider>

Complete Example

Here's a complete example putting it all together:

app/example/page.tsxtypescript

1'use client';
2
3import { DocCentralProvider, PDFViewer, useSDK } from '@doccentral/react';
4
5// Status component to show SDK state
6function SDKStatus() {
7  const { isInitialized, isValidating, validationError, organizationName } = useSDK();
8
9  if (isValidating) {
10    return <div className="p-4 bg-yellow-50">Validating API key...</div>;
11  }
12
13  if (validationError) {
14    return <div className="p-4 bg-red-50 text-red-700">Error: {validationError}</div>;
15  }
16
17  if (isInitialized) {
18    return (
19      <div className="p-4 bg-green-50 text-green-700">
20        Connected to {organizationName}
21      </div>
22    );
23  }
24
25  return null;
26}
27
28// Document viewer component
29function DocumentViewer() {
30  return (
31    <div className="flex flex-col h-screen">
32      <SDKStatus />
33      <div className="flex-1">
34        <PDFViewer
35          documentId="demo-document"
36          documentUrl="/sample.pdf"
37          onSubmit={async (payload) => {
38            // Send to your backend
39            const response = await fetch('/api/documents/submit', {
40              method: 'POST',
41              headers: { 'Content-Type': 'application/json' },
42              body: JSON.stringify(payload),
43            });
44            
45            if (!response.ok) {
46              throw new Error('Submission failed');
47            }
48            
49            console.log('Success!');
50          }}
51        />
52      </div>
53    </div>
54  );
55}
56
57// Main page with provider
58export default function ExamplePage() {
59  return (
60    <DocCentralProvider
61      apiKey={process.env.NEXT_PUBLIC_DOCCENTRAL_API_KEY!}
62      debug={process.env.NODE_ENV === 'development'}
63    >
64      <DocumentViewer />
65    </DocCentralProvider>
66  );
67}

What's Next?

Now that you have a basic integration working, explore these guides to build more sophisticated document workflows: