> ## Documentation Index
> Fetch the complete documentation index at: https://mahmoud-b28887f9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# KPdfViewerConfig: configure zoom, cache, and gestures

> KPdfViewerConfig controls zoom range, swipe navigation, double-tap zoom, RAM and disk cache sizes, and background page preloading for a KPDF viewer instance.

`KPdfViewerConfig` is an immutable configuration object that controls the runtime behavior of a single `KPdfViewerState` instance. You construct it through a builder or a Kotlin DSL, then pass it to `rememberPdfViewerState` or `KPdf.viewerState`. Configuration is fixed for the lifetime of the viewer state — to change behavior, create a new `KPdfViewerState` with updated config.

<Warning>
  Keep your `KPdfViewerConfig` instance stable across recompositions. If you construct a new `KPdfViewerConfig` inline on every recomposition (for example, inside a `@Composable` function body without `remember`), `rememberPdfViewerState` detects the changed config and creates a brand-new viewer state, which resets transient flows such as `openDocumentState` and `saveState`.
</Warning>

## Builder pattern

Call `KPdfViewerConfig.builder()` to get a mutable `Builder`, chain the methods you need, and call `build()` to produce the immutable config.

```kotlin theme={null}
val config = KPdfViewerConfig.builder()
    .enableZoom(true)
    .enableSwipe(true)
    .zoomRange(minZoom = 1f, maxZoom = 5f)
    .doubleTapZoom(2.5f)
    .ramCacheSize(8)
    .diskCacheSize(50)
    .preloadPageCount(2)
    .build()
```

## DSL pattern

The `pdfViewerConfig {}` top-level extension function wraps the builder in a Kotlin DSL block. It is equivalent to the builder pattern and produces the same `KPdfViewerConfig` type.

```kotlin theme={null}
val config = pdfViewerConfig {
    enableZoom(true)
    enableSwipe(true)
    zoomRange(minZoom = 1f, maxZoom = 5f)
    doubleTapZoom(2.5f)
    ramCacheSize(8)
    diskCacheSize(50)
    preloadPageCount(2)
}
```

## Builder methods

<ParamField path="enableZoom" type="Boolean" default="true">
  Enables or disables pinch-to-zoom on the PDF page surface. When `false`, the viewer locks at the minimum zoom level and ignores pinch gestures.
</ParamField>

<ParamField path="enableSwipe" type="Boolean" default="true">
  Enables horizontal swipe to navigate between pages when the viewer is at its base (minimum) zoom level. When `false`, swipe gestures are ignored and you must call `nextPage()`, `previousPage()`, or `goToPage()` programmatically.
</ParamField>

<ParamField path="zoomRange" type="(minZoom: Float, maxZoom: Float)" default="minZoom = 1f, maxZoom = 4f">
  Sets the inclusive pinch-zoom range. `minZoom` must be greater than `0`. `maxZoom` must be greater than or equal to `minZoom`. Throws `IllegalArgumentException` if either constraint is violated.

  The `doubleTapZoom` value is coerced into this range at `build()` time, so you do not need to ensure they are consistent manually.
</ParamField>

<ParamField path="doubleTapZoom" type="Float" default="2f">
  The zoom level applied when the user double-taps the page surface. Must be greater than `0`. At `build()` time the value is coerced into the configured `zoomRange`, so it is safe to specify a value outside that range — it will be clamped automatically.
</ParamField>

<ParamField path="ramCacheSize" type="Int" default="6">
  The maximum number of rendered pages the SDK holds in memory at one time for this viewer instance. A larger value reduces re-render latency when navigating back and forth through pages at the cost of higher memory usage. Set to `0` to disable the in-memory cache entirely.

  Must be `>= 0`.
</ParamField>

<ParamField path="diskCacheSize" type="Int" default="24">
  The maximum number of rendered pages the SDK stores on disk for this viewer instance. A larger value keeps more pages available after they are evicted from RAM, at the cost of additional disk I/O and storage. Set to `0` to disable the disk cache entirely.

  Must be `>= 0`.
</ParamField>

<ParamField path="preloadPageCount" type="Int" default="0">
  The number of pages to render in the background on either side of the current page. For example, a value of `1` preloads one page ahead and one page behind. Set to `0` to disable background preloading. Increasing this value can make page transitions feel instantaneous but raises CPU and memory usage.

  Must be `>= 0`.
</ParamField>

## Default constants

The following compile-time constants are available on the companion object if you want to reference the defaults explicitly:

| Constant                                | Value |
| --------------------------------------- | ----- |
| `KPdfViewerConfig.DefaultRamCacheSize`  | `6`   |
| `KPdfViewerConfig.DefaultDiskCacheSize` | `24`  |

## Full example

```kotlin theme={null}
// In a Composable — wrap in remember to keep it stable
val config = remember {
    pdfViewerConfig {
        enableZoom(true)
        enableSwipe(true)
        zoomRange(minZoom = 1f, maxZoom = 4f)
        doubleTapZoom(2f)
        ramCacheSize(6)
        diskCacheSize(24)
        preloadPageCount(1)
    }
}

val viewerState = rememberPdfViewerState(
    source = source,
    config = config,
)
```