File picker contracts

Guidelines for file picker contracts

Follow these guidelines to customize the file picker for apps that participate in the File Open Picker contract, the File Save Picker contract, or the Cached File Updater contract in order to provide other apps with access to the app's content, a save location, or file updates (respectively).


  • Provide files. Integrating with the File Open Picker contract lets your app provide users and other apps with access to your app's content through the file picker.

  • Provide a save location. Integrating with the File Save Picker contract lets your app provide users and other apps with a save location through the file picker.

    • If your app provides a save location, you should also provide access to your app's content by integrating with the File Open Picker contract.

  • Provide real-time file updates. Integrating with the Cached File Updater contract lets your app perform updates on files in your app's repository and provides updates to local versions of the files in your repository. This lets a user operate on a remote file that your app maintains in its repository as though that file were local. For example, the user could use a text editor app to edit a file and Microsoft OneDrive could update the version of that file in its repository.

    • If your app updates files, it should also provide a save location and access to files by integrating with the File Save Picker contract and the File Open Picker contract, respectively.

Usage guidance

If your app provides files, a save location, or file updates through file pickers, design a page for your app that displays files (or other UI) to the user. This page will be displayed in the center area of the file picker. To learn more about this page and the file picker, see Integrating with file picker contracts.

  • Design your file picker page to adapt to windows of all sizes.

  • Design the page to display in the file picker (your file picker page) based on an existing page that your app uses to display files.

    • If your app is providing files for the user to pick through a file picker, your app should have an existing page that lets users view files. We recommend that you design your file picker page so that it is consistent with this existing file-view page.

    • To further ensure that users feel comfortable with your app's file picker page, use the same (or similar) navigation UI and error reporting for your file picker page as you used for your existing file-view app page. Especially in the case of navigation, users expect similar commands and locations to be available in both the file picker page and the existing file-view page.

  • Design your file picker page around your user's current task.

    • Keep the UI for your file picker page focused on the user's current task, such as helping users pick, save, or update files, by stripping out UI that is not directly related.

    • For example, if a file picker is being used to access files that are provided by your app, remove UI that supports complex and/or detailed navigation, search, or information that cannot be picked.

    • If you want to let the user perform other tasks like consumption, modification, and file management, add controls or other UI for those tasks to your main app. To learn about adding controls, see Adding controls and content.

  • Set the title of the file picker to the name of the user's current location. This gives users a predictable way to orient themselves as they use your app from the file picker.

  • All file locations that are accessible to your app should be accessible from your file picker page. If your app can normally access files in a particular location, your file picker page should also give access to files in that location. If your app has more than one page, access to locations should also be consistent across all file picker pages. This ensures that users have predictable access to files and locations.

  • Use the UI templates and controls available in Microsoft Visual Studio, which has built-in templates that you can use to create the file picker view for your Universal Windows Platform (UWP) apps.

  • Keep sign-in and setup interactions simple when users launch your app through the file picker. If your sign-in or setup tasks are simple (one-step), let users complete those tasks through the file picker so that users don't have to change context.

UX guidelines: File Open Picker contract

  • Display files on your file picker page that are not accessible by using Windows or other apps. Differentiate your app from Windows and other apps by providing access to files in locations that are not accessible from other apps or from Windows, like your app's storage folders or remote servers.

  • Design the UI of your file picker page to respond to the selection mode of the calling app.

    • When an app calls a file picker to access files, the calling app specifies whether the user can pick a single item or multiple items. We recommend that you design your app page to indicate selected files appropriately and differently for each selection mode. For example, if the user is trying to select a profile picture (a single item selection) from files provided by your app, they might tap or click more than one photo while they try to decide which to pick. In this situation, your app UI would only allow one item to be selected at a time. Otherwise, if the user is trying to select multiple files to share with their friends (multiple item selection), your app UI would allow multiple items to be simultaneously selected.

  • For webcam, photography, and camera apps, design the UI of your file picker page around taking pictures.

    • Make sure users can get back into the app that they were using (the calling app or caller) by simplifying your app's UI for your file picker page. Limit the controls you provide on your file picker page to controls that let the user take a picture, and let the user apply a few pre-processing effects (like toggling the flash and zooming).

    • All available controls must be visible on your file picker page because your command bar is not accessible to the user from the file picker. We recommend that you organize these controls on your file picker page similarly to the way they are organized in your command bar, and position them on your file picker page as close as possible (at the top/bottom of the page) to where they appear in your command bar.

UX guidelines: File Save Picker contract

  • Let users save files to locations that are not easily accessible through Windows or other apps, like your app's storage folders or remote storage locations.

  • Change the files displayed on your file picker page based on the file type selected. If the user changes the file type in the file picker's file-type drop-down list, you should update your view to only display files that match the selected file type. Filtering displayed files by type provides the user with an easy, consistent method of identifying the types of files they're interested in.

  • Allow the user to replace a file easily by selecting the file in your app's file picker page. If the user selects a file in your file picker page, you should automatically replace the file name in the file picker file name box so users can easily replace existing files.

UX guidelines: Cached File Updater contract

  • Provide a repository that can track and update files for users. If users use your app as a primary storage location where they regularly save and access files, you may want your app to track some files to provide real-time updates for users.

  • Design your app and file picker page to present a robust repository. If users use your app as a primary storage location for their files, design your app and your associated file picker view to protect against data loss, which could be caused by frequent file updates or conflicting file versions.

  • Let users resolve issues encountered during updates. To help ensure a successful update, your app should notify users in real-time (using UIRequested) when a file is being updated or saved and user intervention is needed to resolve an issue effectively. It's critical that your app helps users to resolve issues with credentials, file version conflicts, and disk capacity.

    • The UI you create should be lightweight and focused specifically on resolving the issue. If more than one step is required (like login), all the steps should be handled in the your app's file picker page. Once complete, your app can enable the file picker commit UI. In addition, your app should update the file picker title to give users context about where they are.

    • If the problem cannot be solved in real-time by the user, or if you simply need to let the user know about what happened (perhaps an error occurred that the user can't resolve), notify the user of the problem the next time your app is launched instead of immediately when the problem occurs via UIRequested.

  • Provide additional information about update and save operations from your normal app pages. Your main app UI should let users manage settings for in-progress and future operations, get information about in-progress and previous operations, and get information about any errors that have occurred.

[This article contains information that is specific to UWP apps and Windows 10. For Windows 8.1 guidance, please download the Windows 8.1 guidelines PDF .]

Related topics

For designers
Quickstart: Integrating with file picker contracts
Quickstart: Accessing files with file pickers
Guidelines for file pickers
For developers (XAML)
For developers (HTML)
Accessing data and files
Adding controls and content
How to share files
Quickstart: Receiving shared content
How to save files through file pickers



© 2016 Microsoft