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.

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.

Builder pattern

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

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.

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

Builder methods

enableZoom · 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.

enableSwipe · 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.

zoomRange · (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.

doubleTapZoom · 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.

ramCacheSize · 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.

diskCacheSize · 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.

preloadPageCount · 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.

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

// 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,
)