Picker Configuration Schema
This outlines the full schema available to configure the picker. These options are passed as shown in the samples.
export type ExtFilter = 'folder' | 'site' | 'documentLibrary' | 'list' | 'onenote' | 'file' | 'media' | 'photo' | 'video' | 'audio' | 'document' | 'listItem' | 'playlist' | 'syntexTemplate' | 'syntexSnippet' | 'syntexField' | `.${string}`;
//NOTE: IItem type references the following docs: https://learn.microsoft.com/en-us/graph/api/resources/driveitem?view=graph-rest-1.0#properties
{
sdk: "8.0";
/**
* Establishes the messaging parameters used to setup the post message communications between
* picker and host application
*/
messaging: {
/**
* A unique id assigned by the host app to this File Picker instance.
* This should ideally be a new GUID generated by the host.
*/
channelId: string;
/**
* The host app's authority, used as the target origin for post-messaging.
*/
origin: string;
/**
* Whether or not the host app window will need to identify itself.
*/
identifyParent?: boolean;
/**
* Whether or not the client app must wait for a 'configure' command to be sent by the host before rendering.
*/
waitForConfiguration?: boolean;
/**
* Override timeout for acknowledgement messages.
*/
acknowledgeTimeout?: number;
/**
* Override timeout for the initialization handshake.
*/
initializeTimeout?: number;
/**
* Override timeout for command responses.
*/
resultTimeout?: number;
};
/**
* Configuration for the entry location to which the File Picker will navigate on load.
* The File Picker app will prioritize path-based navigation if provided, falling back to other address forms
* on error (in case of Site redirection or content rename) or if path information is not provided.
*/
entry: {
sharePoint?: {
/**
* Specify an exact SharePoint content location by path segments.
*/
byPath?: {
/**
* Full URL to the root of a Web, or server-relative URL.
* @example
* 'https://contoso-my.sharepoint.com/personal/user_contoso_com'
* @example
* '/path/to/web'
* @example
* 'subweb'
*/
web?: string;
/**
* Full URL or path segement to identity a List.
* If not preceded with a `/` or a URL scheme, this is assumed to be a list in the specified web.
* @example
* 'Shared Documents'
* @example
* '/path/to/web/Shared Documents'
* @example
* 'https://contoso.sharepoint.com/path/to/web/Shared Documents'
*/
list?: string;
/**
* Path segment to a folder within a list, or a server-relative URL to a folder.
* @example
* 'General'
* @example
* 'foo/bar'
* @example
* '/path/to/web/Shared Documents/General'
*/
folder?: string;
/**
* Auto fallback to root folder if the specified entry sub folder doesn't exist.
*/
fallbackToRoot?: boolean;
};
};
/**
* Indicates that File Picker should start in the Site Pivot
* This pivot is only supported in OneDrive for Business
*/
site?: {};
/**
* Indicates that File Picker should start in the OAL (My Organization) Pivot
* This pivot is only supported in OneDrive for Business
*/
myOrganization?: {};
/**
* Indicates that the File Picker should start in the user's OneDrive.
*/
oneDrive?: {
/**
* Specifies that File Picker should start in the user's Files tab.
*/
files?: {
/**
* Path segment for sub-folder within the user's OneDrive for Business.
* @example
* 'Pictures'
* @example
* '/personal/user_contoso_com/Documents/Attachments'
*/
folder?: string;
/**
* Auto fallback to root folder if the specified entry sub folder doesn't exist.
*/
fallbackToRoot?: boolean;
};
/**
* Indicates that File Picker should start in the user's recent files.
*/
recent?: {};
/**
* Indicates that File Picker should start in the files shared with the user.
*/
sharedWithMe?: {};
/**
* Indicates that File Picker should start in the user's photos.
* This pivot is only available in OneDrive for Consumer
*/
photos?: {};
};
sortBy?: {
/**
* Name of the field *in SharePoint* on which to sort.
*/
fieldName: string;
/**
* Whether or not to sort in ascending order. Default is `true`.
*/
isAscending?: boolean;
};
filterBy?: {
/**
* Name of the field *in SharePoint* on which to filter on.
*/
fieldName: string;
/**
* Filter value
*/
value: string;
};
};
/**
* Specifies how to enable a Search behavior.
*/
search?: {
enabled: boolean;
};
/**
* Configuration for handling authentication requests from the embedded app.
* Presence of this object (even if empty) indicates that the host will handle authentication.
* Omitting this will make the embedded content attempt to rely on cookies.
*/
authentication?: {
/**
* @default true
*/
enabled?: boolean;
/**
* Indicates support for individual token types.
*/
tokens?: {
/**
* @defaultValue true
*/
graph?: boolean;
/**
* @defaultValue true
*/
sharePoint?: boolean;
/**
* @defaultValue false
*/
substrate?: boolean;
};
/**
* Indicates that the host app can handle 'claims' challenges.
*/
claimsChallenge?: {
/**
* @default false
*/
enabled?: boolean;
};
};
/**
* Configures what types of items are allowed to be picked within the experience.
* Note that the default configuration accounts for the expected authentication capabilities of the host app.
* Depending on what else is enabled by the host, the host may be expected to provide tokens for more services and scopes.
*/
typesAndSources?: {
/**
* Specifies the general category of items picked. Switches between 'file' vs. 'folder' picker mode,
* or a general-purpose picker.
* @default 'all'
*/
mode?: "files" | "folders" | "all";
/**
* `filters` options: file extension, i.e. .xlsx, .docx, .ppt, etc.
* `filters` options: 'photo', 'folder', 'video', 'documentLibrary'
*/
filters?: ExtFilter[];
/**
* Specifies a filter for *where* the item may come from.
*/
locations?: {
/**
* Items may only come from the user's OneDrive.
*/
oneDrive?: {};
/**
* Items may only come from a specific location within SharePoint.
*/
sharePoint?: {
byPath?: {
web?: string;
list?: string;
folder?: string;
};
};
};
/**
* Specifies filtering based on user access level.
*/
access?: {
/**
* Filter for requires user access level for picked items. Default is `'read'`.
*/
mode?: "read" | "read-write";
};
/**
* Specifies which pivots the user may access while browsing files and lists.
* Note that if a pivot is disabled here but still targeted in `entry`, it will still be visible in the nav.
*/
pivots?: {
/**
* Show "My files".
*/
oneDrive?: boolean;
/**
* Show "Recent".
*/
recent?: boolean;
/**
* Show "Shared"
*/
shared?: boolean;
/**
* Show "Quick access".
*/
sharedLibraries?: boolean;
/**
* Show "My organization".
* This pivot is only supported in OneDrive for Business
*/
myOrganization?: boolean;
/**
* Show the site pivot
* This pivot is only supported in OneDrive for Business
*/
site?: boolean;
};
};
/**
* Configuration for what item types may be selected within the picker and returned to the host.
*/
selection?: {
/**
* Controls how selection works within the list.
* @default 'single' for the Picker.
*/
mode?: "single" | "multiple" | "pick";
/**
* Whether or not to allow the user to maintain a selection across folders and pivots.
*/
enablePersistence?: boolean;
/**
* Whether or not the host expects to be notified whenever selection changes.
*/
enableNotifications?: boolean;
/**
* The maximum number of items which may be selected.
*/
maximumCount?: number;
/**
* A set of items to pre-select.
*/
sourceItems?: IItem[];
};
/**
* Configures how commands behave within the experience.
*/
commands?: {
/**
* Specifies the behavior for file-picking.
*/
pick?: {
/**
* A special action to perform when picking the file, before handing the result
* back to the host app.
*/
action?: "select" | "share" | "download" | "move";
/**
* A custom label to apply to the button which picks files.
* This must be localized by the host app if supplied.
*/
label?: string;
/**
* Configures the 'move' action for picking files.
*/
move?: {
sourceItems?: IItem[];
};
/**
* Configures the 'copy' action for picking files.
*/
copy?: {
sourceItems?: IItem[];
};
/**
* Configures the 'select' action for picking files.
*/
select?: {
/**
* Specify if we want download urls to be returned when items are selected.
*/
urls?: {
download?: boolean;
};
};
};
/**
* Specifies the behavior for closing the experience.
*/
close?: {
/**
* A custom label to apply to the 'cancel' button.
* This must be localized by the host app if supplied.
*/
label?: string;
};
/**
* Behavior for a "Browse this device" command to pick local files.
*/
browseThisDevice?: {
enabled?: boolean;
label?: string;
mode?: "upload" | "pick";
};
/**
* Behavior for a "From a link" command to pick from a link.
*/
fromALink?: {
enabled?: boolean;
mode?: "nav" | "pivot";
};
/**
* Behavior for a "Switch account" command.
*/
switchAccount?: {
mode?: "host" | "none";
};
/**
* Behavior for a "Manage accounts" command.
*/
manageAccounts?: {
mode?: "host" | "none";
label?: string;
};
/**
* Behavior for "Upload"
*/
upload?: {
enabled?: boolean;
};
/**
* Behavior for "Create folder"
*/
createFolder?: {
enabled?: boolean;
};
/**
* Behavior for "Filter by" in the column headers.
*/
filterByColumn?: {
mode?: "panel" | "menu";
};
/**
* How to handle actions defined by custom formatters.
*/
customFormatter?: {
actions?: {
key: string;
mode?: "host" | "none";
}[];
};
/**
* How to handle specified values for `key` in custom commands
* in the tray, nav, or command bar.
*/
custom?: {
actions?: {
key: string;
/**
* Filters defining what types of items the action operates on.
* If specified, the action will only be available for items which match the given filters.
*/
filters?: ExtFilters[];
/**
* How the action is invoked.
* 'host': Invokes a `custom` command message against the host app.
* 'none': Disables the action.
*/
mode?: "host" | "none";
/**
* Selection criteria to which the item applies.
*/
selection?: "single" | "multiple" | "current" | "none";
}[];
};
};
/**
* Specifies accessibility cues such as auto-focus behaviors.
*/
accessibility?: {
/**
* Whether or not to 'trap focus' within the component. If this is enabled, tab-stops will loop from the last element back to the left navigation automatically.
* This is useful if the components's frame is hosted as the only content of a modal overlay and focus should not jump to the outside content.
*
* @default false
*/
enableFocusTrap?: boolean;
/**
* Whether or not the component should immediately grab focus once the content has loaded.
*
* @default true
*/
trapFocusOnLoad?: boolean;
/**
* Whether or not to force the currently-focused element within the component to be highlighted.
* By default, the focused element is highlighted if the user navigates elements with the keyboard but not when the user interacts via the mouse.
* However, if a host application launches the component due to keyboard input it should set this flag to `true` to ensure continuity of behavior.
*
* @default false
*/
showFocusOnLoad?: boolean;
};
tray?: {
/**
* Configures the commands normally used to pick files or close the picker.
*/
commands?: {
/**
* A key to differentiate the command from others.
*/
key: string;
/**
* A custom string for the command.
* Must be localized by the host.
*/
label?: string;
/**
* The action to perform when the button is clicked.
*/
action: "pick" | "close" | "custom";
/**
* If `'pick'` is specified, which pick behavior to use.
*/
pick?: {
action: "select" | "share" | "download" | "move";
};
/**
* Whether the button should show as the primary button.
*/
primary?: boolean;
/**
* Whether the button should remain visible at all times even if unavailable.
*/
permanent?: boolean;
}[];
/**
* Whether or not the picker tray might be provided by the host instead.
* @defaultValue 'default'
*/
mode?: "host" | "default";
/**
* Configures a component to render in the picker tray to the left of the commands.
* @default 'selection-summary'
*/
prompt?:
| "keep-sharing"
| "selection-summary"
| "selection-editor"
| "save-as"
| "none";
/**
* Configures use of the 'save-as' prompt.
*/
saveAs?: {
/**
* Default file name to show in 'save-as' prompt.
*/
fileName?: string;
};
/**
* Settings for handling conflicts with existing file names.
*/
conflicts?: {
/**
* How to handle when a file name matches an existing file.
* `'warn'` - Show a prompt to ask the user to confirm the choice.
* `'block'` - Block the choice as an error.
* `'accept'` - Accept the choice automatically.
* `'none'` - Do not try to match with existing items.
*/
mode?: "warn" | "block" | "accept" | "none";
};
/**
* Configures use of the 'keep-sharing' prompt.
*/
keepSharing?: {
active?: boolean;
};
};
leftNav?: {
/**
* Whether or not a Left Nav should be rendered by the embedded content.
*/
enabled?: boolean;
/**
* Mode of presentation of the nav.
* If the nav is enabled but this is set to `host`, the embedded app
* will show a button to ask the host app to show a nav.
*/
mode?: "host" | "default";
/**
* Indicates whether the left nav will be initially modal.
*/
initialModality?: "modal" | "hidden";
/**
* Type of left nav
*/
preset?: "oneDrive" | "current-site";
/**
* Custom commands to insert at the end of the left nav. Will appear before the default set.
*/
commands?: {
/**
* Name to use when notifying the host that the command is being invoked.
*/
key: string;
/**
* Localized string to use for the button text.
*/
label: string;
/**
* Type of action which will be performed when the command is clicked.
* 'custom': Configured via `commands.custom`.
*/
action: "custom" | "pick" | "close" | "browse-this-device";
/**
* Name of a Fluent icon to use for the command button.
*/
icon?: string;
}[];
};
/**
* The theme to use for the file-picker. Will change the coloring.
* Note: custom theme objects are expected in addition to the strings below
* @default 'default': Light theme
*/
theme?: "default" | "dark" | "lists";
list?: {
/**
* A custom override for the initial list layout.
*/
layout?: {
/**
* Sets the preferred starting layout for the initial content.
*/
type?: "details" | "compact-details" | "tiles";
};
/**
* Configures scrolling behavior within the Picker.
*/
scrolling?: {
enableStickyHeaders?: boolean;
};
};
/**
* Provides a header title for the Picker.
*/
title?: string;
/**
* Specifies customizations for specific pivots
*/
pivots?: {
/**
* Customize the site pivot
*/
site?: {
byPath?: {
/**
* Chose the site url to use for this pivot
* Required to show the site pivot, if undefined
* the site pivot will not be shown
*/
web?: string;
};
};
};
};