> ## 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.

# PlatformFile

> Create, inspect, and serialize files and directories with one type on every platform

[See the platform support matrix](https://filekit.mintlify.site/platform-support.md#filekit-core)

`PlatformFile` is the file or directory type that every FileKit API takes and returns. It wraps the native representation of each platform (`java.io.File`, Android `Uri`, `NSURL`, a browser `File`) behind one set of properties and functions.

## Create a PlatformFile

On every platform except the web, create a file from a path, or from a parent directory and a child path:

```kotlin nonWebMain theme={null}
val file = PlatformFile("/path/to/document.pdf")
val fromPath = PlatformFile(Path("/path/to/document.pdf")) // kotlinx.io.files.Path

val notes = PlatformFile(FileKit.filesDir, "notes.txt")
val today = FileKit.filesDir / "notes" / "today.txt"
val same = FileKit.filesDir.resolve("notes/today.txt")
```

The file doesn't have to exist yet. Each platform also accepts its native type:

```kotlin androidMain theme={null}
val fromFile = PlatformFile(File("/path/to/document.pdf"))
val fromUri = PlatformFile(uri) // content:// or file:// Uri
```

```kotlin jvmMain theme={null}
val file = PlatformFile(File("/path/to/document.pdf"))
val javaFile: File = file.file
```

```kotlin appleMain theme={null}
val file = PlatformFile(NSURL.fileURLWithPath("/path/to/document.pdf"))
val url: NSURL = file.nsUrl
```

```kotlin webMain theme={null}
// Browsers have no paths: files come from a picker or from the origin private file system
val picked: PlatformFile? = FileKit.openFilePicker()
```

On Android, `PlatformFile(path)` also parses `content://` and `file://` strings into a `Uri`.

## Properties

| Property | Type | Notes |
| - | - | - |
| `name` | `String` | File name with extension, such as `document.pdf`. |
| `extension` | `String` | `pdf`. Empty when the name has none. |
| `nameWithoutExtension` | `String` | `document`. |
| `path` | `String` | The path you created the file with. The `Uri` string for Android `content://` files, the relative path on the web. |
| `size()` | `Long` | Size in bytes. `-1` when unknown: the file doesn't exist, or an Android provider doesn't report a size. `0` for web directories. |
| `lastModified()` | `Instant` | Epoch `0` for web directories. |
| `createdAt()` | `Instant?` | Not on web. Always `null` on Linux native, for Android `content://` files, and before Android 8.0. |
| `mimeType()` | `MimeType?` | `null` for directories and unknown types. See [Check the MIME type](#check-the-mime-type). |
| `parent()` | `PlatformFile?` | `null` at the root. See Android notes below for `content://` files. |
| `isRegularFile()`, `isDirectory()` | `Boolean` | `false` for both when the file doesn't exist. |
| `exists()`, `isAbsolute()` | `Boolean` | Not on web. |
| `absolutePath()`, `absoluteFile()` | `String`, `PlatformFile` | Not on web. Resolves a relative path against the working directory. |
| `toKotlinxIoPath()` | `Path` | Not on web. Throws `FileKitUriPathNotSupportedException` for Android `content://` files. |

`Instant` is `kotlin.time.Instant`. To read the content, see [Reading files](https://filekit.mintlify.site/core/read-file.md). To list, copy, move, or delete, see [File operations](https://filekit.mintlify.site/core/file-operations.md).

## Check the MIME type

```kotlin theme={null}
val type: MimeType? = file.mimeType()
val isImage = type?.primaryType == "image"
```

| Platform | Source of the MIME type |
| - | - |
| Android | The `ContentResolver` for `content://` files, then `MimeTypeMap` from the extension. |
| iOS, macOS, watchOS | Provider metadata (Files app, iCloud Drive), then the extension. Extension-less documents can still resolve. |
| JVM | `Files.probeContentType`, which depends on the operating system's registry. |
| Linux native | The shared MIME database (`/usr/share/mime/globs2`), then `/etc/mime.types`. |
| Windows native | The `Content Type` value of the extension in the Windows registry. |
| Web | The type the browser reports for the file. |

## Serialization

`PlatformFile` is `@Serializable` through `PlatformFileSerializer`, so you can store it in your own serializable classes with the kotlinx.serialization plugin:

```kotlin nonWebMain theme={null}
@Serializable
data class Document(val title: String, val file: PlatformFile)

val json = Json.encodeToString(Document("Report", FileKit.filesDir / "report.pdf"))
val restored = Json.decodeFromString<Document>(json)
```

The file is encoded as its `path` string and decoded with `PlatformFile(path)`.

> [!NOTE]
>
> Serialization keeps the path, not the access rights. A file picked outside your app (an Android `content://` file, a security-scoped file on Apple platforms) may not be readable after a restart: use [bookmark data](https://filekit.mintlify.site/core/bookmark-data.md) for persistent access. On the web, `PlatformFileSerializer` throws at runtime.

## Platform notes

> [accordion] Android: content:// files
>
> Files from pickers are usually `content://` Uris, not filesystem paths. `name` comes from the provider's display name. For Photo Picker Uris that only expose a synthetic name (such as `18.jpg`), FileKit looks up the original name in `MediaStore`, and falls back to a stable name derived from the provider and the Uri.
>
> `parent()` works inside external-storage document trees and keeps access to the selected tree. It returns `null` at the root of the selected directory and for providers whose parent can't be derived from the Uri.

> [accordion] iOS and macOS: security-scoped files
>
> Files picked outside your app's sandbox need security-scoped access. FileKit starts and stops it around each of its own calls on that file. Wrap longer work in `file.withScopedAccess { }`: iterating `walk()` over a picked folder, or passing `nsUrl` to Apple APIs yourself.

> [accordion] Web: browser handles
>
> A picked file is a read-only snapshot of a browser `File`: you can read it, not write it, and there is no path to reopen it later. A directory picker result is a virtual tree built from the selected files, so empty folders are missing, directories report a size of `0`, and their `lastModified()` is epoch `0`. See [Files on the web](https://filekit.mintlify.site/core/web.md).

## Related

* [Reading files](https://filekit.mintlify.site/core/read-file.md) and [Writing files](https://filekit.mintlify.site/core/write-file.md)
* [File operations](https://filekit.mintlify.site/core/file-operations.md): list, walk, copy, move, and delete
* [App directories](https://filekit.mintlify.site/core/file-utils.md): app directories and user folders


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.