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

# Coil 3

> Load and display images from PlatformFile using Coil

<Check>Supported on Android, iOS, macOS, JVM, JS and WASM targets</Check>

## Introduction

FileKit provides seamless integration with [Coil](https://coil-kt.github.io/coil/), a popular image loading library for Kotlin Multiplatform. This integration allows you to easily load and display images from `PlatformFile` objects using Coil's powerful image loading capabilities.

## Configuration

Add the FileKit Coil dependency to your project:

<CodeGroup>
  ```kotlin build.gradle.kts theme={null}
  implementation("io.github.vinceglb:filekit-coil:0.15.0")
  ```

  ```toml libs.versions.toml theme={null}
  [versions]
  filekit = "0.15.0"

  [libraries]
  filekit-coil = { module = "io.github.vinceglb:filekit-coil", version.ref = "filekit" }
  ```
</CodeGroup>

Then, configure Coil in your app's root composable:

```kotlin theme={null}
@Composable
fun App() {
    setSingletonImageLoaderFactory { context ->
        ImageLoader.Builder(context)
            .components {
                addPlatformFileSupport()
            }
            .build()
    }

    MaterialTheme {
        // Your app content
    }
}
```

This setup utilizes the `addPlatformFileSupport()` extension function to register the necessary components within Coil's pipeline, enabling it to handle `PlatformFile` objects:

* **`PlatformFileMapper`**: Maps the `PlatformFile` object to a data type that Coil's fetchers can understand.
* **`PlatformFileFetcher`**: Handles the actual loading of the image data from the `PlatformFile`.
* **`PlatformFileKeyer`**: Generates stable cache keys for `PlatformFile` objects, allowing Coil to effectively cache the loaded images.

## Usage

Once configured, you can use Coil's standard `AsyncImage` composable with `PlatformFile` objects:

```kotlin theme={null}
@Composable
fun ImagePreview(file: PlatformFile) {
    AsyncImage(
        model = file,
        contentDescription = "Image preview",
        modifier = Modifier.fillMaxWidth()
    )
}
```

For more information about using Coil's image loading capabilities, refer to the [official Coil documentation](https://coil-kt.github.io/coil/getting_started/).

## Handling Security-Scoped Resources (iOS/macOS)

On iOS and macOS, if you obtain a `PlatformFile` through mechanisms like the document picker, your app gets temporary, scoped access permission. To ensure Coil can load the image data while this permission is active, FileKit provides the `securelyAccessFile` extension function for `AsyncImagePainter.State`.

Use this function within the `onState` callback of `AsyncImage`:

```kotlin theme={null}
@Composable
fun ImagePreviewScoped(file: PlatformFile) {
    AsyncImage(
        model = file,
        contentDescription = "Image preview",
        modifier = Modifier.fillMaxWidth(),
        onState = { state ->
            // Start/stop security-scoped access based on Coil's state
            state.securelyAccessFile(file)
        }
    )
}
```

This function automatically calls `startAccessingSecurityScopedResource()` when Coil starts loading (`State.Loading`) and `stopAccessingSecurityScopedResource()` when it finishes (`State.Success` or `State.Error`), ensuring the file remains accessible throughout the loading process.

## Example

Here's a complete example showing how to use the Coil integration in a gallery:

```kotlin theme={null}
@Composable
fun App() {
    setSingletonImageLoaderFactory { context ->
        ImageLoader.Builder(context)
            .components {
                addPlatformFileSupport()
            }
            .build()
    }

    MaterialTheme {
        ImageGallery()
    }
}

@Composable
fun ImageGallery(files: List<PlatformFile>) {
    LazyColumn {
        items(files) { file ->
            AsyncImage(
                model = file,
                contentDescription = "Gallery image",
                modifier = Modifier
                    .fillMaxWidth()
                    .height(200.dp),
                contentScale = ContentScale.Crop
            )
        }
    }
}
```

## Next steps

<CardGroup>
  <Card title="PlatformFile" icon="file" href="/core/platform-file">
    Learn more about the core file representation used by FileKit.
  </Card>

  <Card title="Image & Video Utils" icon="image" href="/core/image-and-video-utils">
    Discover more image manipulation utilities provided by FileKit.
  </Card>
</CardGroup>