@stackone/file-picker

StackOne File Picker

Allow your users to select files from your integrations. The @stackone/file-picker introduces an easy-to-use SDK to embed the StackOne file picker into your application.

Install

# NPM
npm install --save @stackone/file-picker

# Yarn
yarn add @stackone/file-picker

Usage

Initialize the File Picker with your options, and then call the open method to open the file picker. Listen to the callbacks to know when a file has been picked or whether the flow has been cancelled. The callback will give you the information about the file picked - you may also retrieve this information by using webhooks or the API. For example purposes, we used React as the framework, but you can use any framework built on top of Javascript/Typescript.

import { FilePicker } from '@stackone/file-picker';

export const FilePickerButton = () => {
  const [filePicker, setFilePicker] = useState<FilePicker | null> (null);

  useEffect(() => {
    const initializePicker = async () => {
      const { sessionToken } = await retrieveAPISessionToken();

      setFilePicker(new FilePicker({ sessionToken }));
    };

    initializePicker();
  }, []);

  const handleClick = useCallback(() => {
    filePicker?.open();
  }, [filePicker]);

  return (
    <button onClick={handleClick} disabled={!filePicker}>
      Open File Picker
    </button>
  );
};

File Picker Options

Apart from the sessionToken, you may pass a few options to customize the File Picker.

// Example of Options object
const options = {
    sessionToken = 'your-session-token',
    containerId = 'file-picker-container',
    baseUrl = 'https://app.stackone.com',
    fields = ['name', 'path', 'driveId'],
    showBranding = false,
    folderSelectionEnabled = true,
    driveSelectionEnabled = true,
    onFilesPicked = (data) => {
        // data may contain files, folders, and/or drives based on what was selected
        if (data.files) {
            console.log('Selected files:', data.files);
        }
        if (data.folders) {
            console.log('Selected folders:', data.folders);
        }
        if (data.drives) {
            console.log('Selected drives:', data.drives);
        }
    },
    onOpen = () => {
            console.log('File picker opened');
        },
    onClose = () => {
        console.log('File picker closed');
    },
    onCancel = () => {
        console.log('File selection canceled');
    }
};

const filePicker = new FilePicker(options);

Name	Type	Required	Description
sessionToken	string	Yes	API session token created in the backend. The session token allows users to have access to their file picker integration.
containerId	string	No	ID of the container element where the file picker will be mounted.
baseUrl	string	No	Which API instance should it connect to.
fields	string[]	No	Which fields from the raw picked file will be mapped on the files picked callback.
showBranding	boolean	No	Show StackOne footer on the file picker, it is defaulted to true.
folderSelectionEnabled	boolean	No	Enable the selection of folders on the unified and native pickers.
driveSelectionEnabled	boolean	No	Enable the selection of drives on the unified and native pickers.
onFilesPicked	function	No	Called when files are selected.
onOpen()	function	No	Called when the file picker is opened.
onClose()	function	No	Called every time the file picker is closed regardless of whether a file has been picked or not.
onCancel()	function	No	Called when the file picker is closed without a file being selected.
onError()	function	No	Called when the file picker has an error.

Callback Data Structure

When you get the callback from the onFilesPicked function, you will receive an object that may contain one or more of the following properties based on what was selected:

• files (optional): An array of selected files
• folders (optional): An array of selected folders when folderSelectionEnabled is true
• drives (optional): An array of selected drives/sites when driveSelectionEnabled is true

Note: The callback will only include the arrays that have items. For example, if only files are selected, only the files property will be present.

File and Folder Types

Files and folders share the same structure:

Name	Type	Required	Description
id	string	Yes	The Unified Id for the file.
name	string	No	The name of the file or folder.
path	string	No	The URL or path of the file or folder.
driveId	string	No	The Drive ID where the file or folder is located.

Drive Type

Drives have a different structure:

Name	Type	Required	Description
id	string	Yes	The Unified Id for the drive.
name	string	No	The name of the drive or site.
type	string	No	Will be 'site' for drives.
createdAt	string	No	The creation date of the drive.

Contribute & Release

This repose uses conventional commit. The repo use semantic-release and the package version is automatically determined based on the commit messages.

Release

Use the Manual release workflow to trigger a release. The package version and changelog will automatically be generated based on conventional commits.