> ## 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: customize zoom, cache, and gestures

> Configure zoom behavior, swipe navigation, memory and disk caching, and page preloading for a KPDF viewer using the builder API or the pdfViewerConfig DSL.

`KPdfViewerConfig` controls runtime behavior for a single KPDF viewer instance: how the user interacts with pages through gestures, how aggressively the SDK caches rendered pages in RAM and on disk, and how many pages to preload in the background. Build a config once, hold it stable in a `remember` block, and pass it to `rememberPdfViewerState`.

## Builder options

<AccordionGroup>
  <Accordion title="enableZoom — Boolean, default true">
    Enable or disable pinch-to-zoom and double-tap zoom on the page surface.

    ```kotlin theme={null}
    .enableZoom(false) // lock the page to a fixed scale
    ```
  </Accordion>

  <Accordion title="enableSwipe — Boolean, default true">
    Allow horizontal swipe gestures to navigate between pages when the viewer is at its base zoom level. Disable this if you want to control navigation exclusively through buttons or your own gesture recognizers.

    ```kotlin theme={null}
    .enableSwipe(false)
    ```
  </Accordion>

  <Accordion title="zoomRange — Float range, default 1f..4f">
    Set the minimum and maximum zoom factors for pinch and double-tap zoom. `minZoom` must be greater than `0` and `maxZoom` must be greater than or equal to `minZoom`.

    ```kotlin theme={null}
    .zoomRange(minZoom = 1f, maxZoom = 6f)
    ```
  </Accordion>

  <Accordion title="doubleTapZoom — Float, default 2f">
    Set the zoom level applied when the user double-taps a page. The SDK clamps this value to the configured zoom range at build time. Must be greater than `0`.

    ```kotlin theme={null}
    .doubleTapZoom(2.5f)
    ```
  </Accordion>

  <Accordion title="ramCacheSize — Int (pages), default 6">
    Set the maximum number of rendered page bitmaps held in RAM for this viewer. Larger values make page turns smoother at the cost of memory. Pass `0` to disable the in-memory cache entirely.

    ```kotlin theme={null}
    .ramCacheSize(10) // keep up to 10 pages in memory
    .ramCacheSize(0)  // disable RAM cache
    ```
  </Accordion>

  <Accordion title="diskCacheSize — Int (pages), default 24">
    Set the maximum number of rendered pages persisted to disk. Disk caching lets the viewer restore pages quickly after they are evicted from RAM. Pass `0` to disable disk caching.

    ```kotlin theme={null}
    .diskCacheSize(50) // cache up to 50 pages on disk
    .diskCacheSize(0)  // disable disk cache
    ```
  </Accordion>

  <Accordion title="preloadPageCount — Int (pages), default 0">
    Set how many pages adjacent to the current page the SDK renders in the background. For example, a value of `2` prerenders 2 pages ahead and 2 behind. Pass `0` to disable background preloading.

    ```kotlin theme={null}
    .preloadPageCount(2) // prerender 2 pages on each side
    ```
  </Accordion>
</AccordionGroup>

## Using the builder

Call `KPdfViewerConfig.builder()`, chain the options you want to override, then call `build()`:

```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()
```

## Using the DSL

The `pdfViewerConfig {}` extension is a Kotlin-idiomatic alternative to the builder. It accepts the same `Builder` receiver, so every option works identically:

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

## Passing config to the viewer

```kotlin theme={null}
@Composable
fun PdfScreen(source: KPdfSource) {
    val config = remember {
        pdfViewerConfig {
            zoomRange(minZoom = 1f, maxZoom = 5f)
            preloadPageCount(2)
        }
    }

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

    KPdfViewer(
        state = viewerState,
        modifier = Modifier.fillMaxSize(),
    )
}
```

<Warning>
  Do not build `KPdfViewerConfig` inline on every recomposition. `rememberPdfViewerState` keys on the `config` reference: if you pass a freshly constructed object each time, it creates a new viewer state instance on every frame and resets transient flows such as `openDocumentState`, `saveState`, and `externalOpenState`.

  ```kotlin theme={null}
  // Correct — config is created once and held stable
  val config = remember { pdfViewerConfig { preloadPageCount(2) } }
  val viewerState = rememberPdfViewerState(source = source, config = config)

  // Avoid — new config on every recomposition recreates viewer state
  val viewerState = rememberPdfViewerState(
      source = source,
      config = pdfViewerConfig { preloadPageCount(2) }, // unstable
  )
  ```
</Warning>

## Default values at a glance

| Option             | Default        |
| ------------------ | -------------- |
| `enableZoom`       | `true`         |
| `enableSwipe`      | `true`         |
| `zoomRange`        | `1f..4f`       |
| `doubleTapZoom`    | `2f`           |
| `ramCacheSize`     | `6` pages      |
| `diskCacheSize`    | `24` pages     |
| `preloadPageCount` | `0` (disabled) |