# @cincel.digital/react

> React wrapper for the pdf viewer providing seamless integration with React components.

Latest version **2.3.0** (published 2026-04-06) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cincel.digital/react
pnpm add @cincel.digital/react
yarn add @cincel.digital/react
bun add @cincel.digital/react
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2026-04-06 |
| First published | 2023-07-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 107.2 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | mautematico, hector.ornelas |

## Links

- npm: https://www.npmjs.com/package/@cincel.digital/react
- npm.io page: https://npm.io/package/@cincel.digital/react

## Dependencies (10)

- [ahooks](https://npm.io/package/ahooks.md) 3.7.7
- [pdfjs-dist](https://npm.io/package/pdfjs-dist.md) ^5.5.207
- [react-fast-compare](https://npm.io/package/react-fast-compare.md) 3.2.2
- [react-tiny-popover](https://npm.io/package/react-tiny-popover.md) 7.2.4
- [@cincel.digital/pdf-viewer](https://npm.io/package/@cincel.digital/pdf-viewer.md) 2.2.1
- [@cincel.digital/react-types](https://npm.io/package/@cincel.digital/react-types.md) 1.2.0
- [@cincel.digital/react-utils](https://npm.io/package/@cincel.digital/react-utils.md) 1.3.0
- [@cincel.digital/object-utils](https://npm.io/package/@cincel.digital/object-utils.md) 1.3.0
- [@cincel.digital/shared-utils](https://npm.io/package/@cincel.digital/shared-utils.md) 2.1.0
- [@cincel.digital/doc-convert-request](https://npm.io/package/@cincel.digital/doc-convert-request.md) 2.1.0

## Recent versions

- 2.3.0 (latest) — 2026-04-06
- 1.3.0-dev.4 (dev) — 2026-03-28
- 2.2.0 — 2026-04-06
- 2.1.0 — 2026-04-06
- 2.1.0-dev.2 — 2026-04-06
- 2.0.3 — 2026-04-02
- 2.0.2 — 2026-04-02
- 2.0.1 — 2026-04-02
- 2.0.0 — 2026-04-02
- 1.3.0-dev.3 — 2026-03-28
- 1.2.9 — 2025-11-15
- 1.2.7 — 2025-11-15
- 1.2.6 — 2025-11-15
- 1.2.5 — 2025-11-15
- 1.2.3 — 2025-11-15
- … 39 more at https://npm.io/package/@cincel.digital/react/versions

## README

# @cincel.digital/react

## Installation

```sh
yarn add @cincel.digital/react

# or

npm i @cincel.digital/react
```

## Usage

### Basic

```tsx
import * as React from "react"
import {
  PDFViewer,
  PdfViewer,
  PdfViewerCloseButton,
  PdfViewerContent,
  PdfViewerRenderer,
  PdfViewerToolbar,
} from "@cincel.digital/react"

const pv = new PDFViewer({ mode: "read" })
pv.debug = true

function IntegrationTest() {
  const [file, setFile] = React.useState<File | null>(null)

  const handleFileUpload = async (
    event: React.ChangeEvent<HTMLInputElement>,
  ) => {
    const file = event.target.files?.[0]
    if (!file) return

    setFile(file)
  }

  return (
    <PdfViewer
      pdfViewer={pv}
      file={file}
      url="https://dev.api.cincel.digital/v3/convert-to-pdf"
      onClose={() => setFile(null)}
      renderEmptyState={(state) => {
        if (state.loading) {
          return <pre>Converting to PDF...</pre>
        } else if (state.empty) {
          return (
            <div>
              <pre>Select a document to convert to PDF.</pre>
              <input
                type="file"
                title="Select a file"
                onChange={handleFileUpload}
              />
              {state.error && <pre>{JSON.stringify(state.error.message)}</pre>}
            </div>
          )
        }
      }}
    >
      <PdfViewerContent>
        <PdfViewerCloseButton />
        <PdfViewerToolbar />
        <PdfViewerRenderer />
      </PdfViewerContent>
    </PdfViewer>
  )
}
```

## Customize the layout

The React integration is built upon an anatomy, which allows for composing the
layout in any desired way. Custom styles can be passed to the Reactish, or
grouped into multiple elements to achieve the desired effect/layout. For
instance, to customize the toolbar, a render prop is provided, enabling the
replacement of the render without complications.

```tsx
<div className="flex space-x-4">
  <PdfViewerToolbar>
    {({ toolbar }) => (
      <div>
        <button onClick={toolbar.fullscreen}>fullscreen</button>
        <button onClick={toolbar.zoomIn}>Zoom in</button>
        <button onClick={toolbar.zoomOut}>Zoom out</button>
      </div>
    )}
  </PdfViewerToolbar>
  <PdfViewerToolbar>
    {({ toolbar }) => (
      <div>
        <button onClick={toolbar.text}>Free text</button>
        <button onClick={() => toolbar.signature("LJGXQo")}>
          Add signature
        </button>
      </div>
    )}
  </PdfViewerToolbar>
</div>
```

This is the value for the Toolbar:

| Property              | Description                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`                | Callback function for the "text" action. Invoked when the "Free text" button is clicked.                                                                    |
| `date`                | Callback function for the "date" action. Invoked when the "Add date" button is clicked.                                                                     |
| `signature(signerId)` | Callback function for the "signature" action. Invoked when the "Add signature" button is clicked. The `signerId` parameter represents the ID of the signer. |
| `zoomIn`              | Function to zoom in the PDF Viewer.                                                                                                                         |
| `zoomOut`             | Function to zoom out the PDF Viewer.                                                                                                                        |
| `fullscreen`          | Function to toggle fullscreen mode for the PDF Viewer.                                                                                                      |

Please note that the annotations(text, date & signature) will only be present if
the Viewer was created in `edit` mode.

```typescript
const pv = new PDFViewer({ mode: "edit" })
```

## Annotations

### Signature

```tsx
const signers: Signer[] = [
  { id: "01", color: "#F77036", name: "Alice" },
  { id: "02", color: "#1EF7DA", name: "Bob" },
]

<PdfViewer
 ...
 signers={signers}
>
 ..
  <PdfViewerToolbar>
    {({ toolbar, signers }) => (
      <div>
        <button onClick={toolbar.text}>Free text</button>
        <button onClick={() => toolbar.signature(signers[0].id)}>Add signature</button>
      </div>
    )}
  </PdfViewerToolbar>
 ..
</PdfViewer>
```

### Date

To utilize the date annotation feature, a two-way data binding needs to be
established. For this purpose, it is essential to pass the `onBeforeDateChange`
property to the toolbar component. This function will be triggered when users
perform a double-click/tap on a date-type annotation. During this event, the
annotation to be modified must be stored in a React state for later use in the
`toolbar.date` method.

```tsx
const [isOpen, actions] = useBoolean()
const [dateToChange, setDateToChange] = React.useState<Annotation<string> | null>(null)

return (<PdfViewer
    .....
>
  <PdfViewerToolbar
    onBeforeDateChange={(annotationToChange) => {
      setDateToChange(annotationToChange)
      actions.setTrue()
    }}
  >
    {({ toolbar }) => {
      return (
        <Popover
          isOpen={isOpen}
          positions={["bottom"]}
          onClickOutside={() => actions.setFalse()}
          content={() => (
            <div
              style={{
                display: "flex",
                flexDirection: "column",
                padding: "8px",
                background: "white",
              }}
            >
              <input
                type="date"
                onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                  // commit the change
                  toolbar.date?.({
                    value: e.target.value,
                    id: dateToChange?.id,
                  })

                  setDateToChange(null)
                  actions.setFalse()
                }}
              />
            </div>
          )}
        >
          <button onClick={actions.toggle}>Date</button>
        </Popover>
      )
    }}
  </PdfViewerToolbar>
</PdfViewer>)
```

---
_Source: https://npm.io/package/@cincel.digital/react · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._