QuickLook

Preview documents, media, and 3D models with QLPreviewController and generate fast, cached file thumbnails with QLThumbnailGenerator in iOS and iPadOS.

SwiftUI QuickLook Previews
UIKit QLPreviewController
Thumbnail Generation with QLThumbnailGenerator
Custom QLPreviewItem Conformance
Common Mistakes
Review Checklist
References

SwiftUI QuickLook Previews

The .quickLookPreview modifier presents system file previews directly from SwiftUI when binding to an optional local URL.

import SwiftUI
import QuickLook

struct DocumentRowView: View {
    let fileURL: URL
    @State private var previewURL: URL?

    var body: some View {
        HStack {
            Image(systemName: "doc.fill")
            Text(fileURL.lastPathComponent)
            Spacer()
            Button("Preview") {
                previewURL = fileURL
            }
        }
        .quickLookPreview($previewURL)
    }
}

UIKit QLPreviewController

For multi-item carousels, custom navigation transitions, or fine-grained preview control, use QLPreviewController.

import UIKit
import QuickLook

@MainActor
final class DocumentPreviewCoordinator: NSObject, QLPreviewControllerDataSource, QLPreviewControllerDelegate {
    private var previewItems: [URL] = []

    func presentPreview(from presenter: UIViewController, files: [URL], startIndex: Int = 0) {
        self.previewItems = files

        let previewController = QLPreviewController()
        previewController.dataSource = self
        previewController.delegate = self
        previewController.currentPreviewItemIndex = startIndex

        presenter.present(previewController, animated: true)
    }

    // MARK: - QLPreviewControllerDataSource

    func numberOfPreviewItems(in controller: QLPreviewController) -> Int {
        previewItems.count
    }

    func previewController(_ controller: QLPreviewController, previewItemAt index: Int) -> any QLPreviewItem {
        previewItems[index] as NSURL
    }
}

Thumbnail Generation with QLThumbnailGenerator

Generate asynchronous, system-cached thumbnails for documents, images, and videos with QLThumbnailGenerator.Request.

import QuickLookThumbnailing
import UIKit

actor ThumbnailLoader {
    static let shared = ThumbnailLoader()
    private let cache = NSCache<NSURL, UIImage>()

    func loadThumbnail(for fileURL: URL, size: CGSize, scale: CGFloat = 2.0) async throws -> UIImage {
        if let cached = cache.object(forKey: fileURL as NSURL) {
            return cached
        }

        let request = QLThumbnailGenerator.Request(
            fileAt: fileURL,
            size: size,
            scale: scale,
            representationTypes: .all
        )

        let representation = try await QLThumbnailGenerator.shared.generateBestRepresentation(for: request)
        let image = representation.uiImage

        cache.setObject(image, forKey: fileURL as NSURL)
        return image
    }
}

Custom QLPreviewItem Conformance

Provide custom titles or encrypted/in-memory file references wrapped in local sandbox files:

import QuickLook

final class PreviewableDocument: NSObject, QLPreviewItem {
    let previewItemURL: URL?
    let previewItemTitle: String?

    init(url: URL, title: String? = nil) {
        self.previewItemURL = url
        self.previewItemTitle = title ?? url.lastPathComponent
        super.init()
    }
}

Common Mistakes

Passing remote web URLs: QuickLook does not stream remote HTTP URLs. Files must be downloaded to a local file URL in the temporary or cache directory before previewing.
Ignoring scale in thumbnail generation: Passing default scale 1.0 produces blurry thumbnails on Retina displays; always pass environment @Environment(\.displayScale) or traitCollection.displayScale.
Blocking main actor with thumbnail loading: Calling synchronous thumbnail APIs freezes the UI; use async generateBestRepresentation(for:) or callbacks.
Retaining temporary preview files indefinitely: Files copied to temp directories for QuickLook preview should be cleaned up after dismiss.
Missing QLPreviewItem URL validity: Passing a file URL pointing to a non-existent file or dangling symlink displays an empty error preview.

Review Checklist

Are target files downloaded locally before passing to QuickLook?
Is .quickLookPreview($url) used for standard SwiftUI single-file previewing?
Does QLPreviewControllerDataSource return valid QLPreviewItem conforming objects?
Does QLThumbnailGenerator.Request pass appropriate size, screen scale, and representation types?
Are generated thumbnails cached in NSCache to prevent redundant disk decodes?
Are temporary files cleaned up when preview presentation is completed?

References

QuickLook Patterns — SwiftUI custom preview sheets, zoom transitions, and thumbnail caching.
QuickLook Documentation — Official Apple QuickLook API reference.
QuickLookThumbnailing Documentation — Asynchronous thumbnail generator reference.
QLPreviewController Guide — UIKit preview controller and delegate methods.

quicklook