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

enableZoom — Boolean, default true

Enable or disable pinch-to-zoom and double-tap zoom on the page surface.

.enableZoom(false) // lock the page to a fixed scale

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.

.enableSwipe(false)

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.

.zoomRange(minZoom = 1f, maxZoom = 6f)

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.

.doubleTapZoom(2.5f)

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.

.ramCacheSize(10) // keep up to 10 pages in memory
.ramCacheSize(0)  // disable RAM cache

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.

.diskCacheSize(50) // cache up to 50 pages on disk
.diskCacheSize(0)  // disable disk cache

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.

.preloadPageCount(2) // prerender 2 pages on each side

Using the builder

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

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:

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

@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(),
    )
}

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.

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

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)