<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "FileProvider",
  "identifier" : "/documentation/FileProvider/NSFileProviderExtension/providePlaceholder(at:completionHandler:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "File Provider"
    ],
    "preciseIdentifier" : "c:objc(cs)NSFileProviderExtension(im)providePlaceholderAtURL:completionHandler:"
  },
  "title" : "providePlaceholder(at:completionHandler:)"
}
-->

# providePlaceholder(at:completionHandler:)

Triggers the creation of a placeholder for the given URL.

```
func providePlaceholder(at url: URL, completionHandler: @escaping @Sendable ((any Error)?) -> Void)
```

## Parameters

`url`

The URL of a shared document.

`completionHandler`

A block that the system calls after the placeholder is created.

    The completion handler takes the following parameter:

- error: If the placeholder was successfully written to disk, this value is `nil`. Otherwise, it holds an `NSError` object describing the error.

## Discussion

> Important:
> You can call this method from synchronous code using a completion handler, as shown on this page, or you can call it as an asynchronous method that has the following declaration:
> 
> ```swift
> func providePlaceholder(at url: URL) async throws
> ```
> 
> For information about concurrency and asynchronous code in Swift, see <doc://com.apple.documentation/documentation/Swift/calling-objective-c-apis-asynchronously>.

The system calls this method when it needs a placeholder for a document that’s returned by the File Provider extension, but is not stored locally. Override `providePlaceholder(at:completionHandler:)` to create a placeholder for the given URL. This task can be broken into three steps: looking up the document’s file provider item, writing the placeholder, and calling the completion handler.

> Important:
> Both the ``doc://com.apple.fileprovider/documentation/FileProvider/NSFileProviderExtension/providePlaceholder(at:completionHandler:)`` and ``doc://com.apple.fileprovider/documentation/FileProvider/NSFileProviderExtension/startProvidingItem(at:completionHandler:)`` methods can be triggered as other processes attempt to access documents provided by the File Provider extension. These methods may be called in response to user interaction with the document browser, or due to a coordinated read or coordinated write of the document’s URL.
> 
> Exactly which methods are triggered, and their sequence, depends on the type of coordinated access. For example, a coordinated read using the `NSFileCoordinatorReadingImmediatelyAvailableMetadataOnly` option triggers only the creation of a placeholder. As a result, your extension should not create dependencies between these methods. They may be called in any order.

### Look Up the Document’s File Provider Item

1. Get the document’s persistent identifier by calling [`persistentIdentifierForItem(at:)`](/documentation/FileProvider/NSFileProviderExtension/persistentIdentifierForItem(at:)), and pass in the value of the `url` parameter.
2. Call [`item(for:)`](/documentation/FileProvider/NSFileProviderExtension/item(for:)), and pass in the persistent identifier. This method returns the file provider item for the document.

### Write the Placeholder

1. Get the placeholder URL by calling [`placeholderURL(for:)`](/documentation/FileProvider/NSFileProviderManager/placeholderURL(for:)), and pass in the value of the url parameter.
2. Call [`writePlaceholder(at:withMetadata:)`](/documentation/FileProvider/NSFileProviderManager/writePlaceholder(at:withMetadata:)), and pass in the placeholder URL and the file provider item.

### Call the Completion Handler

After writing the placeholder to disk, call the completion handler. If any errors occur, pass them to the completion handler. The system then passes the error back to the original coordinated read or write.

### Sample Implementation

```swift
override func providePlaceholder(at url: URL, completionHandler: @escaping (Error?) -> Void) {
    
    guard let identifier = persistentIdentifierForItem(at: url) else {
        completionHandler(NSFileProviderError(.noSuchItem))
        return
    }
    
    do {
        let fileProviderItem = try item(for: identifier)
        
        let placeholderURL = NSFileProviderManager.placeholderURL(for: url)
        try NSFileProviderManager.writePlaceholder(at: placeholderURL,
                                                   withMetadata: fileProviderItem)
        
        completionHandler(nil)
    }
    catch let error {
        completionHandler(error)
    }
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)