> ## 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
> Cross-platform file representation for Kotlin Multiplatform
Supported on Android, iOS, macOS, JVM, Kotlin/Native Linux, JS and WASM targets
## Introduction
`PlatformFile` is the core class in FileKit that provides a unified representation of files across all platforms. It abstracts away platform-specific file implementations and provides a consistent API for working with files in your Kotlin Multiplatform project.
## Creating a PlatformFile
You can create a `PlatformFile` instance in several ways:
```kotlin theme={null}
// From a path string
val file = PlatformFile("/path/to/file.txt")
// From a kotlinx.io.files.Path
val path = Path("/path/to/file.txt")
val file = PlatformFile(path)
// From a parent file and child path
val parentDir = PlatformFile("/path/to")
val file = PlatformFile(parentDir, "file.txt")
// or using the convenient / operator
val file = parentDir / "file.txt"
```
## Platform-specific constructors
Each platform also provides specific constructors:
```kotlin Android theme={null}
// From a Java File
val javaFile = File("/path/to/file.txt")
val file = PlatformFile(javaFile)
// From an Android Uri
val uri = Uri.parse("content://...")
val file = PlatformFile(uri)
```
```kotlin JVM theme={null}
// From a Java File
val javaFile = File("/path/to/file.txt")
val file = PlatformFile(javaFile)
```
```kotlin iOS/macOS theme={null}
// From an NSURL
val nsUrl = NSURL(string = "/path/to/file.txt")
val file = PlatformFile(nsUrl)
```
```kotlin JS/WASM theme={null}
// Web files and virtual directories are provided by FileKit pickers.
val file = FileKit.openFilePicker()
val directory = FileKit.openDirectoryPicker()
```
## Properties
`PlatformFile` provides several properties to access file information:
```kotlin theme={null}
val file = PlatformFile("/path/to/document.pdf")
// Get the file name with extension
val name: String = file.name // "document.pdf"
// Get just the file extension
val extension: String = file.extension // "pdf"
// Get the file name without extension
val nameWithoutExtension: String = file.nameWithoutExtension // "document"
// Get the file path
val path: String = file.path // "/path/to/document.pdf"
// Get the file size in bytes
val size: Long = file.size()
// Note: some provider-backed files may return -1 when size metadata is unavailable.
// Get the parent directory
val parent: PlatformFile? = file.parent()
@OptIn(ExperimentalTime::class)
val createdAt: Instant? = file.createdAt()
@OptIn(ExperimentalTime::class)
val lastModified: Instant = file.lastModified()
// Get the absolute path string
val absolutePath: String = file.absolutePath()
// Get the absolute file
val absoluteFile: PlatformFile = file.absoluteFile()
// Check the MIME type (null for directories or unknown types)
val mimeType: MimeType? = file.mimeType()
```
On Android, `name` is resolved using provider metadata. For Photo Picker URIs, FileKit performs a best-effort lookup of `MediaStore.MediaColumns.DISPLAY_NAME` when providers return synthetic names (for example `18.jpg`), then falls back to a stable provider/URI-derived name if the original filename is not accessible.
On JS/WASM, directory picker results are virtual directory trees built from browser file entries. Empty directories are not exposed by browsers, and directory `lastModified()` values are synthetic.
## File operations
`PlatformFile` provides methods for common file operations:
```kotlin theme={null}
// Check if the file exists
val exists: Boolean = file.exists()
// Check if it's a regular file
val isFile: Boolean = file.isRegularFile()
// Check if it's a directory
val isDirectory: Boolean = file.isDirectory()
// Check if it's an absolute path
val isAbsolute: Boolean = file.isAbsolute()
// Create directories
file.createDirectories()
// Copy the file to a new location
file.copyTo(newFile)
// Move the file to a new location
file.atomicMove(newFile)
// Delete the file
file.delete()
// List files in the directory
val files: List = file.list()
// Get input stream as a source
val source: RawSource = file.source()
// Get output stream as a sink
val sink: RawSink = file.sink(append = false)
// Read bytes from the file
val bytes: ByteArray = file.readBytes()
// Read string from the file
val content: String = file.readString()
// Write bytes to the file
file.write(bytes)
// Write string to the file
file.writeString(content)
```
### Determining MIME types
Use `mimeType()` to ask the underlying platform for the best-known media type. It returns `null` when the value is unknown (for example, directories or proprietary containers).
* **Apple platforms**: FileKit first queries provider metadata (e.g., from the Files app or iCloud Drive) and falls back to the filename extension when needed, so even extension-less documents can resolve to a MIME type.
* **Android**: The resolver consults the `ContentResolver` for `content://` URIs and then falls back to `MimeTypeMap` if necessary.
* **JVM Desktop & Web**: The lookup is derived from the file extension or the desktop platform's MIME registry.
* **Kotlin/Native Linux**: FileKit matches the filename against the system shared MIME database, with `/etc/mime.types` as a fallback.
This utility is helpful when you need to validate file types, populate upload headers, or customise previews based on content.
## Working with directories
You can use the `resolve` method or the `/` operator to navigate through directories:
```kotlin theme={null}
val baseDir = PlatformFile("/path/to/base")
// Create a reference to a subdirectory or file
val subDir = baseDir / "subdirectory"
val file = subDir / "file.txt"
// Alternative using resolve
val file2 = baseDir.resolve("subdirectory/file.txt")
// Get the absolute path from a relative path
val relativeDir = PlatformFile("/path/to/relative")
val absoluteDir: PlatformFile = relativeDir.absoluteFile()
```
## Converting to kotlinx-io
`PlatformFile` provides built-in integration with [kotlinx-io](https://github.com/Kotlin/kotlinx-io).
```kotlin theme={null}
// Convert to kotlinx.io.files.Path
val path: Path = file.toKotlinxIoPath()
// Convert to kotlinx.io.RawSource
val source: RawSource = file.source()
// Convert to kotlinx.io.RawSink
val sink: RawSink = file.sink()
```
## Example usage
```kotlin theme={null}
// Create a file reference
val file = PlatformFile(FileKit.filesDir, "document.txt")
// Check if it exists
if (file.exists()) {
// Write content to the file
file.writeString("Hello, FileKit!")
}
// Read the file content
val content = file.readString()
println(content) // "Hello, FileKit!"
```
## Next steps
Read files as bytes, strings, or streams **across** platforms.
Write data to files with atomic operations and appending.
Compress, resize and save images with platform-specific optimizations.
Access standard directories and common file operations.
Maintain persistent access to user-selected files across app restarts.