# UnoPdf React Package
Welcome to [UnoPdf](https://unopdf.tallcomponents.com), a comprehensive PDF handling library for modern web development from [TallComponents](https://tallcomponents.com). Designed for both frontend and backend applications, UnoPdf offers an extensive suite of web components and a RESTful API to seamlessly integrate PDF functionalities into your projects. Whether you're using Vue, React, or vanilla JavaScript on the frontend, or managing PDFs in backend environments, UnoPdf provides robust tools for creating, editing, reading, and saving PDF documents. Its powerful API also allows access to the PDF object model, enabling developers to build intricate integrations. Embrace the simplicity and versatility of UnoPdf to enhance your web applications with dynamic PDF interactions.
This packages provides React components for UnoPdf. The UnoPdf Core package provides the implementation of the UnoPdf core and is used as a dependency of this React package.
## Installation
```shell
npm install @tallcomponents/unopdf-react
```
or
```shell
yarn add @tallcomponents/unopdf-react
```
## Usage
```tsx
import {
PdfApplication,
PdfDocument,
PdfPages,
defineCustomElements,
} from "@tallcomponents/unopdf-react";
defineCustomElements();
function App() {
return (
);
}
export default App;
```
## More information
A quick start guide and reference documentation is available on the [UnoPdf website](https://unopdf.tallcomponents.com).
## Release notes
UnoPdf is currently available in a private preview and is updated regularly. See the
[UnoPdf Release Notes](https://unopdf.tallcomponents.com/release-notes.html) for more information.
## Code samples
Comprehensive code samples are available on the UnoPdf website:
[UnoPdf React Code Samples](https://unopdf.tallcomponents.com/code-samples/react/)
---
parent: Components
title: pdf-application
nav_order: 1
---
## Overview
The `pdf-application` component is a bridge between the browser and the server-side PDF Viewer API. It manages a session with the API, handles secure communication and authentication, and provides application-level services.
Key Features:
- Manages secure communication with the server-side PDF Viewer API.
- Provides authentication.
- Offers application-level services such as obtaining a list of all uploaded files and controlling storage functions (e.g., deleting files).
To use any other component, a `pdf-application` component must be instantiated first. One session can be used for any number of PDF documents.
The `` element can wrap other components, but this is not required. It has no HTML content and is invisible.
## Usage
Sample usage:
```html
```
For security reasons, it's recommended to use it with a server. If used without a server by providing a public and private key, the security could be compromised.
If no keys are provided, the component expects an endpoint on the current host with url `/api/sessions` to start a session. This endpoint can add the keys and fetch a session token from the PDF API.
See [Authentication](/guide/authentication/) for more information.
## Properties
| Property | Attribute | Description | Type | Default |
| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- |
| `apiBaseUrl` | `api-base-url` | Base URL of the Pdf Api server, for usage with an on-premise Api. | `string \| undefined` | `undefined` |
| `privatekey` | `privatekey` | Private Key used to start a Session on the Pdf Api server. | `string \| undefined` | `undefined` |
| `publickey` | `publickey` | Public Key used to start a Session on the Pdf Api server. | `string \| undefined` | `undefined` |
| `sessionsurl` | `sessionsurl` | URL that points to the backend service that acquires a jwt for authentication (defaults to '/api/sessions'). | `string \| undefined` | `undefined` |
## Events
| Event | Description | Type |
| ---------- | ---------------------------------------- | ------------------------ |
| `apiError` | Event handler used to report Api errors. | `CustomEvent` |
## Methods
### `createDocument(source: string | null, operations: any[], fileName?: string) => Promise`
Create new document
#### Parameters
| Name | Type | Description |
| ------------ | --------------------- | ----------- |
| `source` | `string \| null` | |
| `operations` | `any[]` | |
| `fileName` | `string \| undefined` | |
#### Returns
Type: `Promise`
### `deleteDocument(id: string) => Promise`
Delete single document with given ID
#### Parameters
| Name | Type | Description |
| ---- | -------- | ----------- |
| `id` | `string` | |
#### Returns
Type: `Promise`
### `deleteDocuments(ids: string[]) => Promise`
Delete multiple documents with given IDs
#### Parameters
| Name | Type | Description |
| ----- | ---------- | ----------- |
| `ids` | `string[]` | |
#### Returns
Type: `Promise`
### `getAbout() => Promise`
Get diagnostics
#### Returns
Type: `Promise`
### `getDocuments() => Promise`
Retrieve list of documents
#### Returns
Type: `Promise`
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-bookmarks
nav_order: 5
---
## Overview
The `pdf-bookmarks` component displays the document outline as a tree of bookmark items.
The `document` property identifies the `pdf-document` that provides the bookmarks, if any.
The `pagesviewer` property identifies the `pdf-pages` component that should respond when the user selects a bookmark.
## Usage
```html
```
In this example, a `pdf-document` named "d" is defined. A `pdf-pages` viewer named "p" is associated with this document.
The `pdf-bookmarks` component is also associated with the same document and viewer, allowing the user to navigate the document using bookmarks.
## Properties
| Property | Attribute | Description | Type | Default |
| ------------- | ------------- | ------------------------------------------------------------ | --------------------- | ----------- |
| `document` | `document` | Identifies the PdfDocument component by its 'name' property. | `string \| undefined` | `'default'` |
| `pagesviewer` | `pagesviewer` | Identifies the PdfPages component by its 'name' property. | `string \| undefined` | `'default'` |
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-document
nav_order: 2
---
## Overview
The `` tag creates an invisible component that manages a single PDF document.
Use it in conjunction with other components, such as a page viewer or thumbnail viewer,
to display, modify, and save a PDF document.
The `pdf-document` component manages one PDF document. It can represent a stored document or a new document, plus any unsaved changes.
It does not hold any view state, such as the currently visible page. View state is stored by various [view components](/guide/components/#view-components).
Any number of `pdf-document` components may be constructed; each represents a separate PDF document.
For example, to construct an application that copies pages from one document to another, two `pdf-document` components would be needed, one for the source document, one for the target document.
The `pdf-document` accepts a `name` property. This name is used by other components to reference the document and distinguish it from other `pdf-document` instances.
Therefore, each `pdf-document` must have a unique `name`. If not specified, the `name` is assigned the value `default`. For example, this code:
```html
```
declares a `pdf-uploader` component which will upload a document (from a local file system, for example) into the `pdf-document` component named "document1".
The `pdf-document` has four basic methods that operate on the entire PDF:
- `open(id: string)` retrieves the named PDF from storage and opens it inside the `pdf-document` component.
- `close()` discards the current PDF document.
- `new()` creates a new, empty PDF document.
- `save()` commits unsaved changes to the PDF and saves the PDF to storage. If the document was new, a new ID is created for the document.
In addition, `pdf-document` offers other methods that operate on the document, for example, to set a field value. See the [Methods](#methods) section below for more information.
## Properties
| Property | Attribute | Description | Type | Default |
| -------- | --------- | ----------------------------------------------------------------------------------------------- | --------------------- | ----------- |
| `name` | `name` | Unique ID used by other components to reference this pdf-document component. | `string` | `'default'` |
| `pdfid` | `pdfid` | If specified, automatically opens the named document. A value of "new" creates a new document. | `string \| undefined` | `undefined` |
## Events
| Event | Description | Type |
| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `formdatachanged` | Form data has changed. | `CustomEvent<{ fieldName: string; fieldValue: string \| undefined; }[]>` |
| `loaded` | The document has loaded. All get methods such as getFields return expected values. | `CustomEvent` |
| `unloaded` | The document has unloaded. Methods such as getFields do not return expected values. | `CustomEvent` |
## Methods
### `close() => Promise`
Close the PdfDocument
#### Returns
Type: `Promise`
### `download() => Promise | null>`
Download document
#### Returns
Type: `Promise | null>`
### `downloadAs(format: 'docx' | 'pptx') => Promise | null>`
This function converts the current PDF document to either DOCX or PPTX format and initiates a download.
#### Parameters
| Name | Type | Description |
| -------- | ------------------ | ----------- |
| `format` | `"docx" \| "pptx"` | |
#### Returns
Type: `Promise | null>`
### `getFields() => Promise`
Get document fields.
Use this method if you want to get access to the definitions of form fields in the Pdf document.
If you are only interested in the entered data use `getFormData`.
#### Returns
Type: `Promise`
### `getFormData() => Promise<{ [key: string]: string; }>`
Get form data.
Use this method if you want to get access to the data entered in form fields.
If you are interested in the field definitions of the form fields use `getFields`.
#### Returns
Type: `Promise<{ [key: string]: string; }>`
### `getSummary() => Promise`
Get document summary
#### Returns
Type: `Promise`
### `new() => Promise`
Open a new PdfDocument
#### Returns
Type: `Promise`
### `open(id: string) => Promise`
Open a PdfDocument by document id
#### Parameters
| Name | Type | Description |
| ---- | -------- | ----------- |
| `id` | `string` | |
#### Returns
Type: `Promise`
### `openFile(file: File) => Promise`
Load a PdfDocument from File
#### Parameters
| Name | Type | Description |
| ------ | ------ | ----------- |
| `file` | `File` | |
#### Returns
Type: `Promise`
### `save(fileName?: string) => Promise`
Save the PdfDocument. Note that after saving, the document always has a new ID.
#### Parameters
| Name | Type | Description |
| ---------- | --------------------- | ----------- |
| `fileName` | `string \| undefined` | |
#### Returns
Type: `Promise`
### `setFormData(data: { [key: string]: string; }) => Promise`
Set form data
Use this method if you want to set the data entered by a user in form fields.
#### Parameters
| Name | Type | Description |
| ------ | ---------------------------- | ----------- |
| `data` | `{ [key: string]: string; }` | |
#### Returns
Type: `Promise`
### `setOptions(fieldName: string, options: ListOptionModel[]) => Promise`
Set options
#### Parameters
| Name | Type | Description |
| ----------- | ------------------- | ----------- |
| `fieldName` | `string` | |
| `options` | `ListOptionModel[]` | |
#### Returns
Type: `Promise`
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-layers
nav_order: 6
---
## Overview
The `pdf-layers` component displays the layers of a PDF document, if any.
The `document` property is used to identify the `pdf-document` that provides the layers.
The `pagesviewer` property is used to identify the `pdf-pages` component that should update when the user toggles layer visibility.
## Usage
```html
```
In this example, a `pdf-document` named "d" is defined. A `pdf-pages` viewer named "p" is associated with this document.
The `pdf-layers` component is also associated with the same document and viewer, allowing the user to toggle the visibility of layers in the document.
## Properties
| Property | Attribute | Description | Type | Default |
| ------------- | ------------- | --------------------------------------------------------- | --------------------- | ----------- |
| `document` | `document` | Reference for the PdfDocument | `string \| undefined` | `'default'` |
| `pagesviewer` | `pagesviewer` | Identifies the PdfPages component by its 'name' property. | `string \| undefined` | `'default'` |
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-pages
nav_order: 3
---
## Overview
The `pdf-pages` component displays pages of a single PDF document.
This component can display pages in one of two modes:
- PageMode.Single: one page is displayed in the component's frame at a time. Scrolling moves to a new page immediately; there is no continuous scrolling, where a portion of a preceding or subsequent page is displayed.
- PageMode.Multi: the component's frame displays all pages of the document in a scrolling window. Scrolling is continuous; the window can display portions of adjacent pages.
This component maintains a zoom factor, which controls the magnification of the document's pages, expressed as a percentage of the original page size. The zoom factor defaults to 100%.
## Usage
When declaring a `` component, set the `document` property to reference the desired `` component.
(This is not necessary if there is only one `pdf-document` component.)
Sample usage:
```html
>
```
## Properties
| Property | Attribute | Description | Type | Default |
| ------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ---------------- |
| `debugUserMode` | `debug-user-mode` | Debug user mode - shows a border for userMode | `boolean` | `false` |
| `document` | `document` | Reference to the pdf-document component, whose PDF pages this viewer will display. This value should match the value of the desired document's `name` property. | `string \| undefined` | `'default'` |
| `focusWidget` | -- | This widget has input focus. May be null. | `IPdfWidget \| null` | `null` |
| `name` | `name` | Unique ID used by other components to reference this pdf-pages component. | `string \| undefined` | `'default'` |
| `pageMode` | `page-mode` | View mode - PageMode.Single or PageMode.Multi - determines if the viewer shows one page or multiple. | `PageMode.Multi \| PageMode.Single` | `PageMode.Multi` |
| `showCustomWidget` | -- | If this function returns true, then the passed widget, when it has input focus, is replaced with a custom widget. A custom widget is provided as a child element of this component. Attribute `slot` must be set to `customWidget`. | `(widget: IPdfWidget) => boolean` | `() => false` |
## Events
| Event | Description | Type |
| -------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `focuswidgetchanged` | The widget that has input focus changes. May be null. | `CustomEvent` |
| `pageindexchanged` | The pageIndex of the PdfViewer has changed | `CustomEvent` |
| `rectangleselect` | The user finished drawing a selection rectangle | `CustomEvent<{ pageIndex: number; x: number; y: number; width: number; height: number; }>` |
| `usermodechanged` | The mode of the PdfViewer has changed | `CustomEvent` |
| `zoomfactorchanged` | The zoomFactor of the PdfViewer has changed | `CustomEvent` |
## Methods
### `addImage(pageIndex: number, bottom: number, left: number, width: number, height: number, image: any) => Promise`
#### Parameters
| Name | Type | Description |
| ----------- | -------- | ----------- |
| `pageIndex` | `number` | |
| `bottom` | `number` | |
| `left` | `number` | |
| `width` | `number` | |
| `height` | `number` | |
| `image` | `any` | |
#### Returns
Type: `Promise`
### `addText(pageIndex: number, bottom: number, left: number, text: string, fontName: string, fontSize: number, color: string) => Promise`
#### Parameters
| Name | Type | Description |
| ----------- | -------- | ----------- |
| `pageIndex` | `number` | |
| `bottom` | `number` | |
| `left` | `number` | |
| `text` | `string` | |
| `fontName` | `string` | |
| `fontSize` | `number` | |
| `color` | `string` | |
#### Returns
Type: `Promise`
### `getFocusWidget() => Promise`
#### Returns
Type: `Promise`
### `getPageIndex() => Promise`
Get the index of the current page of the PdfViewer
#### Returns
Type: `Promise`
### `getPageMode() => Promise`
Get the page mode of the PdfViewer
#### Returns
Type: `Promise`
### `getUserMode() => Promise`
#### Returns
Type: `Promise`
### `getZoomFactor() => Promise`
Get the zoom factor of the PdfViewer
#### Returns
Type: `Promise`
### `gotoPage(pageIndex: number) => Promise`
Make page with given zero-based index current.
#### Parameters
| Name | Type | Description |
| ----------- | -------- | ----------- |
| `pageIndex` | `number` | |
#### Returns
Type: `Promise`
### `setHighlightFields(highlight: boolean) => Promise`
Set highlight fields for the PdfViewer
#### Parameters
| Name | Type | Description |
| ----------- | --------- | ----------- |
| `highlight` | `boolean` | |
#### Returns
Type: `Promise`
### `setPageMode(mode: PageMode) => Promise`
Set the page mode of the PdfViewer
#### Parameters
| Name | Type | Description |
| ------ | ---------- | ----------- |
| `mode` | `PageMode` | |
#### Returns
Type: `Promise`
### `setUserMode(userMode: UserMode) => Promise`
#### Parameters
| Name | Type | Description |
| ---------- | ---------- | ----------- |
| `userMode` | `UserMode` | |
#### Returns
Type: `Promise`
### `toggleLayer(name: string) => Promise`
Toggle the visibility of a layer in the PdfViewer
#### Parameters
| Name | Type | Description |
| ------ | -------- | ----------- |
| `name` | `string` | |
#### Returns
Type: `Promise`
### `zoom(factor: number) => Promise`
Sets the zoom or magnification factor of the page. The factor is a floating point number representing the amount of magnification to apply to the display of the page.
For example:
- a value of 1.0 displays the page at original size.
- a value of 2.0 displays it at twice the original size.
- a value of 0.5 displays it at half the original size.
#### Parameters
| Name | Type | Description |
| -------- | -------- | ----------- |
| `factor` | `number` | |
#### Returns
Type: `Promise`
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-thumbnails
nav_order: 4
---
## Overview
The `pdf-thumbnails` component displays a sequence of thumbnail images corresponding to the pages of the associated document.
In addition to a `document` property, the `pdf-thumbnails` component can also specify a `pagesviewer`;
in this case, selecting a thumbnail causes the named viewer to scroll to the corresponding page.
In this way, the `` element can control the viewer's current page selection.
## Usage
When creating a `pdf-thumbnails` component, use the `document` property to identiy the `pdf-document` to be displayed.
## Properties
| Property | Attribute | Description | Type | Default |
| ------------- | ------------- | -------------------------------------------------------------------------------- | -------------------------------- | ----------- |
| `direction` | `direction` | Layout thumbnails from left to right in a row or from top to bottom in a column. | `"column" \| "row" \| undefined` | `'row'` |
| `document` | `document` | Identifies the PdfDocument component by its 'name' property. | `string \| undefined` | `'default'` |
| `pagesviewer` | `pagesviewer` | Identifies the PdfPages component by its 'name' property. | `string \| undefined` | `'default'` |
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*
---
parent: Components
title: pdf-uploader
nav_order: 7
---
## Overview
The `pdf-uploader` component can load a PDF document into a `pdf-document` component. The `pdf-uploader` does this in one of two ways:
- if the user clicks in the `` area, a file selection dialog appears; the selected file is loaded.
- otherwise, when the user drags and drops a file into the `` area, the dropped file is loaded.
The `pdf-uploader` component accepts a `document` property which identifies the particular `` element into which the file will be loaded.
If no `document` property is supplied, a value of "default" will be assumed.
## Usage
Sample usage:
```html
```
In this case, the `` element's name is assumed to be "default", and the `` element's document property is also assumed to be "default".
## Properties
| Property | Attribute | Description | Type | Default |
| ------------- | ------------- | ----------------------------------------------------------------------------------------- | --------------------- | ----------- |
| `document` | `document` | Reference to the pdf-document component, into which this component will upload documents. | `string \| undefined` | `'default'` |
| `pagesviewer` | `pagesviewer` | Identifies the PdfPages component by its 'name' property. | `string \| undefined` | `'default'` |
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*