# PdfProviders

Source: https://sdk.pdf.net/docs/v1/reference/PdfProviders



The root provider of the SDK. It hosts the document and viewport state and accepts the configuration, so every SDK hook and component must be rendered inside it.

All props are optional; together they form the `Config` type. The PDF application re-renders whenever a prop changes identity, so keep the props referentially stable: define static configuration outside the component and memoize the rest (see [Getting started](https://sdk.pdf.net/docs/v1/guides/getting-started)).

| Prop                     | Type                          | Default                            | What it does                                                                      |
| ------------------------ | ----------------------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
| `theme`                  | `Partial<Theme>`              | `{ viewportPadding: 10 }`          | The appearance: padding, class names, styles, and component overrides. See below. |
| `initialInteractionTool` | `InteractionTool`             | `{ type: 'select' }`               | The interaction tool active when the viewport first mounts.                       |
| `initialContentPolicy`   | `ContentPolicy`               | `CONTENT_POLICY_PRESET.PDF_EDITOR` | The content policy applied when the viewport first mounts.                        |
| `zoomGestures`           | `ZoomGestureControllerConfig` | see below                          | Tunes the built-in wheel and pinch zoom.                                          |
| `dragGestures`           | `Partial<DragGestureConfig>`  | see below                          | Tunes when a press becomes a drag, per pointer type.                              |
| `debugHotkeysEnabled`    | `boolean`                     | `false`                            | Enables the SDK's internal debug hotkeys.                                         |

The interaction tool and the content policy are described in [useInteractionTool](https://sdk.pdf.net/docs/v1/reference/useInteractionTool) and [CONTENT_POLICY_PRESET](https://sdk.pdf.net/docs/v1/reference/CONTENT_POLICY_PRESET); change them later with [useSetInteractionMode](https://sdk.pdf.net/docs/v1/reference/useSetInteractionMode).

## Theme [#theme]

`Theme` fields, all optional:

| Field             | Type                                        | What it does                                                                                                  |
| ----------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `viewportPadding` | `number \| number[]`                        | The gap between the pages and the viewport edges, in pixels. Follows the CSS padding shorthand.               |
| `classNames`      | `Partial<Record<StyleKeys, string>>`        | Class names appended to the elements the SDK renders.                                                         |
| `styles`          | `Partial<Record<StyleKeys, CSSProperties>>` | Inline styles applied to the elements the SDK renders. They take precedence over the SDK's own inline styles. |
| `components`      | see below                                   | Custom components rendered in place of, or in addition to, the built-in ones.                                 |

`StyleKeys` names the styleable elements: `scrollViewport`, `pagesContainer`, `page`, `pageCanvas`, `rubberbandSelection`, `resizable`, `resizableHandle`, `widgetOverlay`, `widgetPreview`, `widgetInput`, `widgetSignature`, `widgetSignatureHint`, `imagePreview`, and `searchMatch`. The [Theming and customization](https://sdk.pdf.net/docs/v1/guides/theming-and-customization) guide describes each element and the CSS variables.

`searchMatch` is the highlighted text of a search match. It is part of the text layout, so its `styles` must use paint properties only, such as `background` or `color`, and lengths with units (`'4px'`, not `4`): a padding, margin, or border would move the text. A `classNames` class can style the active match apart with a `[data-active]` selector.

### Components [#components]

`theme.components` fields, all optional:

| Field           | Value                                                                                            | What it does                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `pageOverlay`   | a component receiving `PageOverlayProps`, or a React node                                        | Rendered over each visible page, above the page content. No overlay by default. |
| `widgetOverlay` | a component with the props of [WidgetOverlay](https://sdk.pdf.net/docs/v1/reference/WidgetOverlay), or a React node | Replaces the highlight drawn over each form widget.                             |
| `widgetPreview` | a component with the props of [WidgetPreview](https://sdk.pdf.net/docs/v1/reference/WidgetPreview), or a React node | Replaces the box that follows the cursor while placing a widget.                |

* A replacement can render the exported built-in component for the cases it doesn't customize.
* A string is taken as an HTML element name, such as `'div'`, not as text.
* `PageOverlayProps` are `pageId`, `pageIndex` (zero-based), and `className`. Add `className` to the overlay's root element: it positions the overlay over the page. The overlay sits above the page content, so give the parts that shouldn't intercept clicks `pointer-events: none`.

## Zoom gestures [#zoom-gestures]

`zoomGestures` fields, all optional:

| Field                 | Default | What it does                                                                                                      |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `minScale`            | `0.5`   | The lowest scale reachable by zoom gestures.                                                                      |
| `maxScale`            | `4`     | The highest scale reachable by zoom gestures.                                                                     |
| `wheelFactorIn`       | `100`   | The wheel delta, in pixels, that doubles the scale when zooming in: larger means slower zoom.                     |
| `wheelFactorOut`      | `75`    | The wheel delta, in pixels, that halves the scale when zooming out: larger means slower zoom.                     |
| `wheelGestureTimeout` | `300`   | The pause between wheel events, in milliseconds, after which a wheel zoom gesture ends.                           |
| `delayBetweenEvents`  | `100`   | The time, in milliseconds, after a zoom gesture or a scale animation ends before the next zoom gesture can start. |

The bounds don't limit [useViewportScale](https://sdk.pdf.net/docs/v1/reference/useViewportScale), which sets any positive scale.

## Drag gestures [#drag-gestures]

`dragGestures` is keyed by `PointerType` (`mouse`, `pen`, `touch`), and each entry is a `PointerConfiguration` deciding when a press on a draggable element turns into a drag, in one of two shapes:

* `{ promoteDelay, requireActive? }` (`TimerPointerConfiguration`): the drag starts when the pointer is held still for `promoteDelay` milliseconds; moving it earlier cancels the drag. Suits low-precision input, such as touch.
* `{ suppressTime, suppressDistance, requireActive? }` (`SuppressPointerConfiguration`): pointer movement within `suppressDistance` pixels during the first `suppressTime` milliseconds is ignored, so a shaky click isn't taken for a drag. Suits high-precision input, such as a mouse.

`requireActive` limits dragging to elements that are already selected, which keeps unselected blocks from interfering with scrolling on touch devices. By default, mouse and pen use `{ suppressTime: 150, suppressDistance: 10 }`, and touch uses `{ promoteDelay: 300 }`; a pointer type left out keeps its default.

## Example [#example]

```tsx
import { useMemo } from 'react'
import { CONTENT_POLICY_PRESET, PageOverlayProps, PdfProviders } from '@sdk-pdf/react'

function PageNumberOverlay({ pageIndex, className }: PageOverlayProps) {
  return (
    <div className={className} style={{ pointerEvents: 'none' }}>
      <span className="page-number">{pageIndex + 1}</span>
    </div>
  )
}

export function App({ viewportPadding }: { viewportPadding: number }) {
  const config = useMemo(
    () => ({
      theme: { viewportPadding, components: { pageOverlay: PageNumberOverlay } },
      initialContentPolicy: CONTENT_POLICY_PRESET.PDF_VIEWER,
    }),
    [viewportPadding]
  )

  return (
    <PdfProviders {...config}>
      <DocumentLoader />
    </PdfProviders>
  )
}
```