UIDocumentPickerViewController — What It Is, Working with iOS Documents

What is UIDocumentPickerViewController?

UIDocumentPickerViewController is a UIKit controller that provides a system interface for selecting documents. It is part of the UIKit framework and is available since iOS 8. The controller displays a file browser that includes local storage, iCloud Drive, and registered third-party cloud services.

The controller works asynchronously: after calling present, the user sees a system dialog, selects a file, and the result is returned through the delegate. The app does not require special permissions to access the selected file — the system picker automatically provides temporary access to the URI.

UIDocumentPickerViewController supports iPad via UIPopoverPresentationController and an adaptive interface for iPhone. Since iOS 14, the controller has received an updated design and sidebar navigation support in iPadOS.

Import and Export Modes

UIDocumentPickerViewController operates in two main modes, each determining how the app accesses the file. The mode is set via the forOpeningContentTypes or forExporting parameter depending on the task.

Import mode (forOpeningContentTypes) copies the selected file to the app sandbox. The app receives a URL to its own copy of the file, accessible only to it. This is a safe mode: the file from another app is not modified, and the copy is fully controlled by the current app.

Export mode (forExporting) provides a URL to the original file without copying. The app can read the file via the link, but changes are not saved back. This mode is used when you need to transfer a file to another app or send it by email. For writing changes, the open mode with scoped security-scoped URL is used.

Picker Configuration and UTI Filtering

UTI (Uniform Type Identifier) is a content type identification system in the Apple ecosystem. UIDocumentPickerViewController filters displayed files by the UTI array passed through forOpeningContentTypes. If no UTI is specified, the picker shows all file types.

• PDF — com.adobe.pdf. The picker shows only PDF documents.
• Images — public.image. Includes JPEG, PNG, HEIC, and other formats.
• Text — public.plain-text. Displays .txt, .csv, and other text files.
• Audio — public.audio. Includes MP3, AAC, WAV, and Lossless formats.
• Video — public.movie. Shows MP4, MOV, AVI, and other video formats.

To select multiple types, pass an array [UTType.pdf, UTType.image]. Since iOS 14, Apple recommends using UTType instead of string constants. UIDocumentPickerViewController automatically updates the list of displayed types when the selected provider changes.

Swift Code Example: Selecting a Document

Implementation of UIDocumentPickerViewController in Swift is minimal: create a controller instance with UTI types, set the delegate, and call present. After the file is selected, the delegate receives an array of URLs in the didPickDocumentsAt method. Each URL is a security-scoped reference that requires calling startAccessingSecurityScopedResource.

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // read file from url
}

Security-Scoped Resources

A security-scoped URL requires calling startAccessingSecurityScopedResource before reading. This method tells the system that the app is gaining temporary access to a file outside the sandbox. After finishing, always call stopAccessingSecurityScopedResource, otherwise the system may block access.

UIDocumentPickerDelegate and Result Handling

UIDocumentPickerDelegate receives file selection results through two methods: didPickDocumentsAt on success and didPickDocumentsAt on cancellation. iOS automatically calls the cancellation method if the user closes the picker without making a selection.

Error handling includes checking URL availability. If the user selected a file from iCloud Drive but the device is offline, the URL may be inaccessible. It is recommended to check FileManager.default.isReadableFile before reading and show the user a clear error message.

For iOS 14+, a new method documentPicker:didPickDocumentsAt with an array of URLs is available. The old method didPickDocumentAt (single) is deprecated. Always handle the array, even if allowsMultipleSelection is disabled — Apple recommends using a single handler.

UIDocumentPickerViewController on iPad

iPad requires special configuration of UIDocumentPickerViewController. On iPad, the picker is displayed as a popover and must specify a sourceView for correct positioning. Without sourceView, the controller may crash with an exception on iPadOS.

For the popover, the popoverPresentationController property is used. Specify sourceView and sourceRect to anchor it to a button or table cell. On iPhone this code has no effect — iOS automatically displays the picker full screen. Since iPadOS 16, the controller supports sidebar and split view for improved navigation.

The adaptive design of UIDocumentPickerViewController automatically switches between full-screen (iPhone) and popover (iPad). The developer does not need to implement separate controllers for different devices — it is enough to correctly configure the popoverPresentationController for iPad.