Add a powerful PDF editor directly into your React App.

Easily add [SimplePDF](https://simplepdf.com) to your React app, by using the `EmbedPDF` component. ## [Demo](https://codesandbox.io/p/sandbox/m8p3gz) ## Install ```sh npm install @simplepdf/react-embed-pdf ``` The package root (``, `useEmbed`) has no `zod` dependency. Only the agentic tools, the opt-in [`@simplepdf/react-embed-pdf/ai-sdk`](#agentic--useembedtools-vercel-ai-sdk) subpath, need `zod` (a peer). Install it alongside if you use them (npm 7+ adds it automatically; pnpm / Yarn PnP users must add it explicitly): ```sh npm install zod ``` ## Related documentation For shared product behavior and account-specific features, see the main embed README: - [Data Privacy & `companyIdentifier`](../README.md#data-privacy--companyidentifier) - [Branding Configuration](../README.md#branding-configuration) - [Retrieving PDF Data](../README.md#retrieving-pdf-data) - [Page Manipulation](../README.md#page-manipulation) - [FAQ](../README.md#faq) ## How to use it The `EmbedPDF` component has two modes: `"modal"` (default) and `"inline"`. **[List of all available props](#available-props)** ### Account-specific features _The features below require a [SimplePDF account](https://simplepdf.com/pricing#g)_ While the component does not require any account to be used (without any limits), you can specify the `companyIdentifier` to: - [Automatically collect your users' submissions, configure webhooks, and use BYOS](../README.md#retrieving-pdf-data) - [Customize branding and white-label behavior](../README.md#branding-configuration) - [Use company mode instead of the default mode](../README.md#data-privacy--companyidentifier) _Example_ ```jsx import { EmbedPDF } from '@simplepdf/react-embed-pdf'; Opens sample.pdf ; ``` ### Modal mode Modal is the default, just wrap any HTML element and the editor opens in a modal on the user's click. You don't need the `mode` prop; pass `mode="modal"` only if you want to be explicit. ```jsx import { EmbedPDF } from "@simplepdf/react-embed-pdf"; // Opens the PDF on click Opens sample.pdf // Let the user pick the PDF ``` ### Inline mode Render the PDF editor directly in your app ```jsx import { EmbedPDF } from "@simplepdf/react-embed-pdf"; // The PDF is displayed when rendering the component // The PDF picker is displayed when rendering the component ``` ### Viewer mode only Specify `react-viewer` as `companyIdentifier` to disable the editing features: ```jsx import { EmbedPDF } from '@simplepdf/react-embed-pdf'; // The PDF is displayed using the viewer: all editing features are disabled ; ``` See [Data Privacy & `companyIdentifier`](../README.md#data-privacy--companyidentifier) for reserved values and mode behavior. ### Programmatic Control _Some actions require a SimplePDF account. See [Retrieving PDF Data](../README.md#retrieving-pdf-data) for storage and submission behavior._ `const { embedRef, actions } = useEmbed();` drives the editor imperatively (`actions`); the agentic `tools` come from the opt-in `@simplepdf/react-embed-pdf/ai-sdk` subpath (`useEmbedTools(embedRef)`). Attach `embedRef` to the component: ``. #### Imperative: `actions` Actions are camelCase (the editor's snake_case wire is transformed for you). `useEmbed().actions` exposes the FULL editor surface; the most common: | Action | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `actions.goTo({ page })` | Navigate to a specific page | | `actions.selectTool({ tool })` | Select a tool: `'TEXT'`, `'COMB_TEXT'`, `'CHECKBOX'`, `'PICTURE'`, `'SIGNATURE'`, or `null` to deselect | | `actions.detectFields()` | Automatically detect form fields in the document | | `actions.deleteFields({ fieldIds?, page? })` | Delete fields by id or page, or all fields if both are omitted | | `actions.getDocumentContent({ extractionMode })` | Extract document content (`'auto'` or `'ocr'`) | | `actions.setFieldValue({ fieldId, value })` | Set a field's value | | `actions.submit({ downloadCopy })` | Submit the document | …plus `createField`, `getFields`, `focusField`, `movePage`, `rotatePage`, `deletePages`, `download`, and `loadDocument`. All actions return a `Promise` with a result object: `{ success: true, data: ... }` or `{ success: false, error: { code, message } }`. ```jsx import { EmbedPDF, useEmbed } from '@simplepdf/react-embed-pdf'; const Editor = () => { const { embedRef, actions } = useEmbed(); const handleSubmit = async () => { const result = await actions.submit({ downloadCopy: false }); if (result.success) console.log('Submitted!'); }; const handleExtract = async () => { const result = await actions.getDocumentContent({ extractionMode: 'auto' }); if (result.success) console.log('Pages:', result.data.pages); }; return ( <> ); }; ``` **"Fill and read this document for me"** is just these actions in sequence, exactly what an AI agent calls on your behalf (read the fields, fill one, then walk the user to a signature: navigate to its page, focus it, open the signature tool): ```jsx const { embedRef, actions } = useEmbed(); const fields = await actions.getFields(); // read await actions.setFieldValue({ fieldId: 'f_full_name', value: 'Jane Doe' }); // fill await actions.goTo({ page: 3 }); await actions.focusField({ fieldId: 'f_signature' }); await actions.selectTool({ tool: 'SIGNATURE' }); ``` #### Agentic: `useEmbedTools` (Vercel AI SDK) The agentic tools live in the opt-in `@simplepdf/react-embed-pdf/ai-sdk` subpath, importing it is what pulls `zod`, so a non-agentic app never loads it (mirroring `@simplepdf/embed`'s `/ai-sdk`). `useEmbedTools(embedRef)` binds the SimplePDF tool set to the live editor, drop it straight into the AI SDK and an LLM can drive the editor: ```jsx import { useChat } from '@ai-sdk/react'; import { EmbedPDF, useEmbed } from '@simplepdf/react-embed-pdf'; import { useEmbedTools } from '@simplepdf/react-embed-pdf/ai-sdk'; const CopilotEditor = () => { const { embedRef } = useEmbed(); const tools = useEmbedTools(embedRef); useChat({ tools }); // the model's tool calls run against the live editor return ; }; ``` For server-side tool definitions (execute-less, for `streamText`), import `simplePDFToolDefinitions` from the React-free core `@simplepdf/embed/ai-sdk` (it is intentionally not re-exported from this React subpath, which imports React). `embedRef.current` is the flat editor-actions handle, every camelCase operation, with the deprecated `selectTool` / `submit` overloads; subscribe to editor events via the `onEmbedEvent` prop. (The framework-free `@simplepdf/embed` core exposes the grouped `embed.actions` / `embed.events` / `embed.lifecycle` handle for non-React use.) #### Agentic: `useEmbedTools` (TanStack AI) The TanStack mirror lives in the opt-in `@simplepdf/react-embed-pdf/tanstack-ai` subpath (importing it pulls `@tanstack/ai`). `useEmbedTools(embedRef)` returns the editor-bound client tools; pass them to `clientTools(...)`, then `useChat`: ```jsx import { useChat, clientTools } from '@tanstack/ai-react'; import { EmbedPDF, useEmbed } from '@simplepdf/react-embed-pdf'; import { useEmbedTools } from '@simplepdf/react-embed-pdf/tanstack-ai'; const CopilotEditor = () => { const { embedRef } = useEmbed(); const tools = clientTools(...useEmbedTools(embedRef)); useChat({ connection, tools }); // the model's tool calls run against the live editor return ; }; ``` On your server `chat({ tools })` route, register `simplePDFToolDefinitions()` imported from the React-free core `@simplepdf/embed/tanstack-ai` (not from this React subpath, which would pull React into your server) so the model is aware of the tools. See [Retrieving PDF Data](../README.md#retrieving-pdf-data) for text extraction, downloading, and server-side storage options. ### Available props

Name	Type	Required	Description
ref	EmbedActions	No	The live editor-actions handle, for programmatic control (see Programmatic Control). Attach the `embedRef` from `useEmbed()`.
mode	"inline" \| "modal"	No (defaults to "modal")	Inline the editor in your layout, or display it inside a click-to-open modal
locale	"en" \| "de" \| "es" \| "fr" \| "it" \| "nl" \| "pt"	No (defaults to "en")	Language to display the editor in (ISO locale)
children	React.ReactElement	Yes in "modal" mode	Elements triggering the editor
companyIdentifier	string	No	Your SimplePDF portal. See Data Privacy & companyIdentifier for reserved values and data handling details.
baseDomain	string	No	Override the editor's base domain (defaults to `simplepdf.com`)
context	Record<string, unknown>	No	Sent via webhooks
onEmbedEvent	`(event: EmbedEvent) => Promise<void> \| void`	No	Events sent by the Iframe
document	{ url: string } \| { dataUrl: string } \| { file: File \| Blob }	No	The document to open (same typed shape as `createEmbed`): a URL (CORS / authenticated same-origin / a SimplePDF documents URL), a data URL, or a File/Blob
style	React.CSSProperties	No	Available for inline mode only
className	string	No	Available for inline mode only

## How to dev 1. Link the widget ```sh npm link npm start ``` 2. Use it in the target application ```sh npm link @simplepdf/react-embed-pdf ```