> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # File Picker > Merge's embedded File Picker UI for browsing files, folders, and drives in a connected File Storage account. Built into Merge Link. Merge's File Picker is built into our embedded Merge Link component and provides a user-friendly interface for your customers to browse Files, Folders, and/or Drives in their connected File Storage account. File Picker does not impact your File Storage Linked Account syncs unlike [Selective Sync](https://help.merge.dev/en/articles/9113654-selective-sync). --- ## Demo video Watch this quick video to learn the basics of how Merge's File Picker works. ![File Picker demo](/_fern-files/merge-test.docs.buildwithfern.com/62f728af853cd47b5453fec46799117d4213fc34900aa75f10ca81b63cf31143/docs/src/assets/gifs/filepicker.gif) --- ## Setting up Merge Link with File Picker To set up File Picker, please follow our [Embedded Link guide](/get-started/link/) to add our drop-in Merge Link component to your app. > **Warning** > > Make sure you have the latest version of [react-merge-link](https://github.com/merge-api/react-merge-link) Enabling the File Picker only requires a few additions to **step 2.** In addition to following step 2 of our Embedded Link guide, you will need to add a new parameter `filePickerConfig`. `onSubmit` is the only required input to `filePickerConfig`, and returns an array of selected objects from your user's workspace. This input is a callback and is left as `console.log()` in this example for you to decide how to handle Files, Folders, and Drives that your users have selected in the File Picker. If you are testing the File Picker in your dashboard, no callback is provided and the File Picker will automatically close on submit. In this example, the File Picker configuration allows multi-select of Files and Folders. See details about each `filePickerConfig` input below. **`Frontend - Initial link with File Picker`** ```jsx {11-16,24-29} Frontend - Initial link with File Picker import React, { useCallback } from "react"; // In your React project folder, run: // npm install --save @mergeapi/react-merge-link import { useMergeLink } from "@mergeapi/react-merge-link"; const onSuccess = useCallback((public_token) => { // Send public_token to server (Step 3) }, []); // highlight-start const onSubmit = useCallback((output_objects) => { // handle selected Files, Folders, or Drives for (output_object of output_objects) { console.log(output_object); } }, []); // highlight-end const { open, isReady } = useMergeLink({ linkToken: "ADD_GENERATED_LINK_TOKEN", // Replace ADD_GENERATED_LINK_TOKEN with the token retrieved from your backend (Step 1) onSuccess, // **** FILE PICKER CONFIG BELOW IS NEW FOR FILE PICKER **** // // highlight-start filePickerConfig: { onSubmit, // required types: ['FILE', 'FOLDER'], // optional allowMultiSelect: true // optional } // highlight-end }); ``` --- ## Configuration inputs | Input | Type | Description | | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `types` | Array | Optional array of object types that determines which types of objects your users can pick. Possible values for object types include: `FILE`, `FOLDER`, `DRIVE`. If `types` is empty, your users will be able to pick objects of any type. If `types` is not empty, your users are restricted to selecting from the object types in the array. For example, if `types = ['FILE', 'FOLDER']`, your users will be able to select Files and Folders, but not Drives. | | `allowMultiSelect` | Boolean | Optional boolean field that allows your users to select multiple objects in one File Picker session. The default value is `false`, which restricts your users to only select one object. | | `onSubmit` | Function | Callback that returns an array of `MergeFileStorageData` objects as its output. See an example for `MergeFileStorageData` below. | --- ## Merge File Storage data `MergeFileStorageData` properties should match our File Storage Common Model properties for the given workspace object type. Select the object type to see its corresponding properties and example response. #### File The File object is used to represent a file in the workspace. The response properties match the [File Common Model](/filestorage/files/). **`Example File response`** ```json Example File response { "id": "45ce474c-dhcj-43a6-754r-629f799f7d68", "remote_id": "12", "name": "merge_article.txt", "file_url": "https://drive.com/1234567890/merge_article.txt", "file_thumbnail_url": "https://drive.com/1234567890/merge_article_thumbnail.txt", "size": 1024, "mime_type": "text/plain", "description": "This file contains an article about Merge.", "folder": "fba1fbc6-67c0-4cb2-a176-7896acd2ffd5", "permissions": ["fba1fbc6-67c0-4cb2-a176-7896acd2ffd5"], "drive": "fba1fbc6-67c0-4cb2-a176-7896acd2ffd5", "remote_created_at": "2022-02-11T00:00:00Z", "remote_updated_at": "2022-02-11T00:00:00Z", "remote_was_deleted": false, "created_at": "2022-02-11T00:00:00Z", "modified_at": "2022-02-11T00:00:00Z" } ``` #### Folder The Folder object is used to represent a folder in the workspace. The response properties match the [Folder Common Model](/filestorage/folders/). **`Example Folder response`** ```json Example Folder response { "id": "fba1fbc6-67c0-4cb2-a176-7896acd2ffd5", "remote_id": "34", "name": "Documents", "folder_url": "https://drive.com/1234567890/Documents", "size": 25600, "description": "This folder contains important documents.", "parent_folder": "e1b6c4f9-a8b9-4f72-81c3-9d3b2a1c0e4d", "drive": "fba1fbc6-67c0-4cb2-a176-7896acd2ffd5", "permissions": ["fba1fbc6-67c0-4cb2-a176-7896acd2ffd5"], "remote_created_at": "2022-01-15T00:00:00Z", "remote_updated_at": "2022-02-11T00:00:00Z", "remote_was_deleted": false, "created_at": "2022-01-15T00:00:00Z", "modified_at": "2022-02-11T00:00:00Z" } ``` #### Drive The Drive object is used to represent a drive in the workspace. The response properties match the [Drive Common Model](/filestorage/drives/). **`Example Drive response`** ```json Example Drive response { "id": "fba1fbc6-67c0-4cb2-a176-7896acd2ffd5", "remote_id": "56", "name": "My Drive", "remote_created_at": "2022-01-01T00:00:00Z", "drive_url": "https://drive.com/1234567890", "remote_was_deleted": false, "created_at": "2022-01-01T00:00:00Z", "modified_at": "2022-02-11T00:00:00Z" } ```