rememberPdfViewerState: Compose viewer state factory

rememberPdfViewerState creates a KPdfViewerState, wires platform save and open flows, and disposes the state when the composable leaves the composition.

rememberPdfViewerState is the recommended entry point for integrating KPDF into a Compose Multiplatform screen. It constructs a KPdfViewerState via KPdfFactory.create(), binds the three platform-native side-effect handlers for document open, save, and external-open flows, triggers an initial open() call for the given source, and disposes the state cleanly when the composable leaves the composition. Calling this function once is all you need before passing the returned state to KPdfViewer, KPdfViewerToolbar, and KPdfThumbnailStrip.

Signature

@Composable
fun rememberPdfViewerState(
    source: KPdfSource,
    config: KPdfViewerConfig = KPdfViewerConfig.builder().build(),
): KPdfViewerState

Parameters

source · KPdfSource · required

Describes where the PDF comes from. Supported subtypes are:

• KPdfSource.Url(url: String, headers: Map<String, String> = emptyMap()) — fetches from a remote URL, with optional HTTP headers.
• KPdfSource.Bytes(bytes: ByteArray) — loads from in-memory bytes.
• KPdfSource.Base64(base64: String) — decodes a Base64-encoded PDF string.

The state is keyed on source inside remember(source, config, sdk) { … }. Providing a new source instance that is not equal to the previous one causes the SDK to create a new viewer state and immediately call open() on the new source. Keep source stable across recompositions — see the stability warning below.

config · KPdfViewerConfig

Controls runtime viewer behaviour. Defaults to KPdfViewerConfig.builder().build() which applies all SDK defaults. Build a custom config with the builder:

KPdfViewerConfig.builder()
    .enableZoom(true)
    .enableSwipe(true)
    .zoomRange(minZoom = 1f, maxZoom = 5f)
    .doubleTapZoom(2f)
    .ramCacheSize(6)
    .diskCacheSize(24)
    .preloadPageCount(2)
    .build()

Like source, config is a remember key. Rebuilding a new KPdfViewerConfig inline on every recomposition recreates the entire viewer state. Wrap it in remember { … } or hoist it to a stable scope.

Return value

Returns a KPdfViewerState instance that is remembered for the lifetime of the composable and disposed when it leaves the composition. Pass it to connected views:

KPdfViewer(state = viewerState)
KPdfViewerToolbar(state = viewerState, …)
KPdfThumbnailStrip(state = viewerState, …)

What the function does internally

1. Creates the SDK facade — KPdfFactory.create() is called once and remembered independently of source and config.
2. Creates the viewer state — sdk.viewerState(source, config) is called inside remember(source, config, sdk). A new state is produced only when source or config changes.
3. Opens the document — A LaunchedEffect(state, source) calls state.open(source) on the IO dispatcher.
4. Binds platform effects — Platform-native file-picker and intent callbacks are registered automatically for save, open, and external-open flows on Android and iOS.
5. Disposes on leave — state.close() is called when the composable leaves the composition, releasing all resources including cached pages.

Usage

@Composable
fun PdfScreen(source: KPdfSource) {
    // Keep source stable — wrap in remember if it might be rebuilt upstream
    val stableSource = remember(source) { source }

    val viewerConfig = remember {
        KPdfViewerConfig.builder()
            .zoomRange(minZoom = 1f, maxZoom = 5f)
            .doubleTapZoom(2f)
            .ramCacheSize(6)
            .diskCacheSize(24)
            .preloadPageCount(2)
            .build()
    }

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

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

source and config are remember keys. If either value is reconstructed on every recomposition — for example, a KPdfSource.Url(...) call or a KPdfViewerConfig.builder().build() call written directly inside the composable body — rememberPdfViewerState creates a new KPdfViewerState on every frame. This resets all observable states including openDocumentState, saveState, and externalOpenState, and cancels any in-flight platform picker session.

Always compute source and config inside remember { … } or hoist them to a ViewModel before passing them to rememberPdfViewerState.

Manual state creation

If you need to manage the viewer lifecycle yourself — for example inside a custom ViewModel or outside of Compose — create the state directly:

val sdk = KPdfFactory.create()
val viewerState = sdk.viewerState(
    source = KPdfSource.Url("https://example.com/file.pdf"),
    config = KPdfViewerConfig.builder().build(),
)

// Open the document
viewerState.open(source)

// Release resources when done
viewerState.close()

When creating the state manually you are responsible for calling open(), binding any platform effects, and calling close() at the appropriate lifecycle point.

Notes

• You should use one KPdfViewerState per visible viewer instance. Do not share a single state between two simultaneously visible KPdfViewer composables.
• KPdfViewer, KPdfViewerToolbar, and KPdfThumbnailStrip all read from the same KPdfViewerState, so you only call rememberPdfViewerState once per screen.
• state.close() is idempotent — calling it more than once is safe and has no effect after the first call.