---
title: "providePlaceholder(at:completionHandler:)"
framework: fileprovider
role: symbol
role_heading: Instance Method
path: "fileprovider/nsfileproviderextension/provideplaceholder(at:completionhandler:)"
---

# providePlaceholder(at:completionHandler:)

Triggers the creation of a placeholder for the given URL.

## Declaration

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

```swift
func providePlaceholder(at url: URL) async throws
```

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

## Discussion

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: func providePlaceholder(at url: URL) async throws For information about concurrency and asynchronous code in Swift, see 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 providePlaceholder(at:completionHandler:) and 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 Get the document’s persistent identifier by calling persistentIdentifierForItem(at:), and pass in the value of the url parameter. Call item(for:), and pass in the persistent identifier. This method returns the file provider item for the document. Write the Placeholder Get the placeholder URL by calling placeholderURL(for:), and pass in the value of the url parameter. Call 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 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)     } }

## See Also

### Managing shared files

- [itemChanged(at:)](fileprovider/nsfileproviderextension/itemchanged(at:).md)
- [startProvidingItem(at:completionHandler:)](fileprovider/nsfileproviderextension/startprovidingitem(at:completionhandler:).md)
- [stopProvidingItem(at:)](fileprovider/nsfileproviderextension/stopprovidingitem(at:).md)