Skip to main content
Guidelines for file picker contracts

Applies to Windows and Windows Phone

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).

Dos and don'ts

  • Provide files. Integrating with the File Open Picker contract lets your app provide users and other apps 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 provide updates to local versions of the files in your repository. From the users' perspective, this lets them to 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.

Additional usage guidance

If your app provides files, a save location, or file updates through file pickers, you need to 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.

A screen shot of a file picker with the center area emphasized to show where the app page will be loaded.

This screen shot has been modified to emphasize and label the center area of a file picker window to show where your app's page (the file picker page) will be loaded.

 

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

    • Applies to Windows

    Note  Windows 8.1 displays file pickers in windows as narrow as 320 pixels. To make the most of a narrow display, consider reducing the left margin of your file picker page to 20 pixels and using vertical scrolling when loading in a window fewer than 500 pixels wide. Note that the file picker item template in Microsoft Visual Studio supports vertical scrolling in windows fewer than 500 pixels wide and horizontal scrolling in larger windows. For more information on item templates, see JavaScript item templates for Store apps or C#, VB, and C++ item templates for Store apps.

  • 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. Making these two pages consistent with each other helps users feel comfortable and familiar with how your app displays files in the file picker.

    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 use for your existing file-view app page. Especially in the case of navigation, users expect similar commands and locations using 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, like helping users pick, save, or update files, by stripping out UI that is not directly related. This helps make sure that using the file picker is a quick, in-and-out experience that gets users back into the app they were using (the calling app or caller).

    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. The title, which is highlighted in this screen shot, appears in top bar of the file picker letterbox.

    In this screen shot, the title is Pictures Library, which lets the user know where they are in their system. You should update this title whenever the user navigates to a different location.

    A cropped screen capture of a file picker windows that shows the title highlighted.

     

  • 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. Access to locations should also be consistent across all file picker pages, if your app has more than one page. This ensures that users have predictable access to files and locations.

  • Use the UI templates and controls available in Microsoft Visual Studio.

    Visual Studio has built-in templates that you can use to create the file picker view for your Windows Store apps. For more information on item templates, see JavaScript item templates for Store apps or C#, VB, and C++ item templates for Store 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) you should let users complete those tasks through the file picker so that users don't have to change context. You should avoid asking users to complete multi-step interactions through the Share charm. Instead, tell users to open your app directly to complete more complex interactions. When you use your main app to complete complex interactions you ensure that you have the space to organize those tasks clearly and effectively.

Additional UX guidelines: File Open Picker contract

  • Display files in your file picker page in a unique and relevant way.

    Organize and display files in a way (or ways) that is unique to your app and ensures that your page is both convenient and relevant to users. This should still be consistent with what users see in the view that your app uses to display files within the app.

  • 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 selected simultaneously.

  • 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 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 app 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 app 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 app bar.

Additional UX guidelines: File Save Picker contract

A screen capture of a file picker with the center area emphasized to show where the app page will be loaded.

This modified screen shot emphasizes the center area of a file picker window where the page that displays your app's save location will be loaded.

 

  • Provide save locations that are not accessible to users through Windows or other apps.

    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 file type in the file picker's file-type drop-down list, you should update your view to display only 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.

Additional 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 to 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 is especially important that your app help users 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 gives users context about where they are.

    If the problem cannot be solved in real time by the user, or if you simply need let the user know what happened (perhaps an error occurred that the user can't resolve), we recommend that you 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.

Security Considerations

The following articles provide guidance for writing secure C++ code.

Related topics

For designers
Quickstart: Integrating with file picker contracts
Quickstart: Accessing files with file pickers
Guidelines for file pickers
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
For developers (XAML)
Windows.Storage.Pickers
Windows.Storage.Pickers.Provider
Windows.Storage.AccessCache