DO NOT USE

This has been deprecated and will be deleted in a future release. Please refrain from new implementations.

This component has been removed from the system. The File Select base component is now managed in documents-js-monorepo.

Props

NameTypeRequiredDefaultDescription
accept
string | string[]
false

Set accepted file types. Accepts everything if left undefined

since

10.19.0

hideDropzone
boolean
false

Hide dropzone and render only default "Attach File(s)" button.

default

false

since

10.19.0

hideLocalSource
boolean
false

Hide local files source in file explorer modal

since

10.19.0

maxFileNumber
number
false

Maximum number of files that can be selected

since

10.19.0

maxFileSize
number
false

Maximum file size (in bytes)

since

10.19.0

minFileSize
number
false

Minimum file size (in bytes)

since

10.19.0

uploadFile
UNSAFE_UploadFile
false

A function for manually controlling the network request for file upload. An alternative to using getEndpoint which handles the network request itself.

since

10.19.0

afterHide
Function
false

A callback to be invoked after the file explorer modal closes

since

11.1.0

beforeLocalFileUpload
Function
false

Optional async function that is invoked when selecting or dropping in a local file. If you want to restrict certain uploads, you can use this callback. Returning true continues the upload, while false will prevent upload.

since

10.19.0

dropzoneContentRenderer
Function
false

An optional content renderer for the dropzone. Accepts { open, disabled, errorMessage } as a single argument, allowing to control the dropzone and display different content depending on dropzone state

since

10.19.0

getEndpoint
Function
false

A function returning an upload URL for a given file. An alternative to uploadFile which allows manual control of the network request for file upload.

since

10.19.0

getHeaders
Function
false

A function returning an upload request headers. Returns empty object by default.

since

10.19.0

getMethod
Function
false

A function returning an upload HTTP method for a given file. Returns POST by default.

since

10.19.0

getPayload
Function
false

A function returning an upload payload FormData object for a given file. When defined, getPayloadKey is ignored.

since

10.19.0

getPayloadKey
Function
false

A function returning an upload payload FormData key for a given file. Returns file by default.

since

10.19.0

getTokenLabel
Function
false

Customize the token label for a given source value. By default, sourceValueEntry.name is returned.

since

10.19.0

localSourceDropzoneContentRenderer
Function
false
onAdd
Function
false

To be called every time when the files are uploaded directly or attached via file explorer. The input data should be appended to the current value. Files with upload errors are omitted.

since

10.19.0

onError
Function
false

To be called whenever an upload error occurs

since

10.19.0

onFileTokenClick
Function
false

To be called when attached file receives a click

since

10.19.0

onProgress
Function
false

To be called whenever the upload progress is changed

since

10.19.0

onRemove
Function
false

To be called whenever the file is removed by user from the primary token list. Removed item should be deleted from the current value by id key

since

10.19.0

onUploadStateChange
Function
false

To be called whenever upload state is changed

since

10.19.0

FileSelect provides ways of implementing sophisticated UX scenarios related to file selection and uploading. It provides a set of predefined source types such as TreeSource, GridSource and LocalSource, but implementors can make sources of their own, too. (see "Custom Source" section)

Usage

FileSelect is an uncontrolled component; its state can be obtained via the lifecycle hooks such onAdd, onRemove, onProgress and onError. If needed, ref can be used to control the value of file select (e.g. to set the initial value).

FileSelect handles uploading routine and stores server response under FileSelectValueEntry['response'] key. All the HTTP related settings can be configured using the following methods: getEndpoint, getPayloadKey, getPayload, getHeaders, getMethod.

maxFileNumber and accept props can be used to control the amount of files and the type of files allowed.

container prop can be used to set the container element of the modal.

LocalSource

NameTypeRequiredDefaultDescription
accept
string | string[]
false

Set accepted file types. Accepts everything if left undefined

since

10.19.0

maxFileSize
number
false

Maximum file size (in bytes)

since

10.19.0

minFileSize
number
false

Minimum file size (in bytes)

since

10.19.0

onCancel
((item: ThumbnailListItem) => void)
false
qafalse
since

10.19.0

sourceId
string
true
since

10.19.0

uploadFile
UNSAFE_UploadFile
false
(file: File,{' '} {`{ onProgress: (progress: number) => void onSuccess: (response: unknown) => void onError: (error: unknown) => void }`} ) => string

A function for manually controlling the network request for file upload. An alternative to using getEndpoint which handles the network request itself.
since

10.19.0

beforeLocalFileUpload
Function
true

Optional async function that is invoked when selecting or dropping in a local file. If you want to restrict certain uploads, you can use this callback. Returning true continues the upload, while false will prevent upload. {'(files: ThumbnailListItem[]) => Promise'}

since

10.19.0

dropzoneContentRenderer
Function
false

An optional content renderer for the dropzone. Accepts{' '} {'{ open, disabled, errorMessage }'} as a single argument, allowing to control the dropzone and display different content depending on dropzone state

since

10.19.0

getEndpoint
Function
false

(file: File) => string

A function returning an upload URL for a given file. An alternative to uploadFile which allows manual control of the network request for file upload.

since

10.19.0

getHeaders
Function
false

(file: File) => object

A function returning an upload request headers. Returns empty object by default.

since

10.19.0

getMethod
Function
false

(file: File) => HTTPRequestMethod

A function returning an upload HTTP method for a given file. Returns POST by default.

since

10.19.0

getPayload
Function
false

(file: File) => FormData

A function returning an upload payload FormData{' '} object for a given file. When defined, getPayloadKey is ignored.

since

10.19.0

getPayloadKey
Function
false

(file: File) => string

A function returning an upload payload FormData key for a given file. Returns file by default.

since

10.19.0

GridSource

NameTypeRequiredDefaultDescription
colStackCapfalse

Sets a breakpoing at which columns will start stacking on top of each other. E.g. if set to "tabletMd" - columns will stack on "tabletMd", "tabletSm" and "mobileLg" breakpoints.

since

10.19.0

gutterX
GridSpacing
false

If given a spacing string value (e.g. "sm" or "none"), sets horizontal column spacing across all breakpoints. Horizontal gutters are ignored when columns are stacked.

If given an object, sets horizontal column spacing for given breakpoints (keys in configuration object, e.g. {"tabletMd": "xs", "mobileLg": "none"}).

since

10.19.0

gutterY
GridSpacing
false

If given a spacing string value (e.g. "sm" or "none"), sets vertical column spacing across all breakpoints.

If given an object, sets vertical column spacing for given breakpoints (keys in configuration object, e.g. {"tabletMd": "xs", "mobileLg": "none"}).

since

10.19.0

TreeSource

NameTypeRequiredDefaultDescription
expandedfalse

Array of keys of the expanded nodes

since

10.19.0

icon
ReactNode
true
deprecated

String icon variant is deprecated, use the React components directly from the @procore/core-icons/dist package

since

10.19.0

isLoading
boolean
false

Show/Hide loading indicator of the content

since

10.19.0

optionstrue
since

10.19.0

sourceId
string
true
since

10.19.0

title
string
true
since

10.19.0

getChildren
Function
false

Should return an array of children nodes. {'(node: Node): Node[]'}

since

10.19.0

getLabel
Function
false

This function will be executed on each node. Should return{' '} label for row {'(node: Node): string'}

since

10.19.0

getParentId
Function
false

This function can be used to override the default parent detection mechanism. If not defined, Node['parentId'] is used to get a given node's parent. {'(node: Node): TreeNodeId'}

since

10.19.0

deprecated

Returning UNSAFE_treeRootNodeId to determine a root node is deprecated. Return null or undefined intead.

deprecatedsince

11.9.0

getRoot
Function
false

Function should return a single root node or an array of root nodes {'(): Node | Node[]'}

since

10.19.0

deprecated

To be removed in future release. getParentId should be used to determine root nodes instead.

deprecatedsince

11.9.0

getType
Function
false

This function will be executed on each node. Should return{' '} 'branch' or 'leaf' {'(node: Node): NodeType'}

since

10.19.0

isExpandable
Function
false

Function of whether to enable tree node expansion/collapsing. {'(node: Node): boolean'}

since

10.19.0

isSelectable
Function
false

Function of whether to enable tree node selection. {'(node: Node): boolean'}

since

10.19.0

onChange
Function
false

Callback function fired with currently selected array of nodes. (nodes: DefaultNode[]) => void

since

10.19.0

onExpand
Function
false

Triggers when current node expand {'(node: Node): Promise'}

since

10.19.0

Custom sources

Source is represented with a child component of FileSelect that registers itself via FileSelectSourceContext.register. The return value of FileSelectSourceContext.register can be used to unregister.

Sources must render themselves only when sourceId equals FileSelectSourceContext.currentSource.

When source value changes, it must call FileSelectSourceContext.onChange API with the new source value. This is required for FileSelect to keep track of added values.

Upon modal submission, FileSelect resets the value, so sources need to implement value reset logic and expose it via register.

When mapping source values to file select values, the original source values are stored under FileSelectValueEntry['origin'] key.

Source should respect maxFileNumber and not allow adding more values if its exceeded.

Sources should subscribe for reset event by using FileSelectSourceContext.onResetValue and reset their current value themselves. The return value of FileSelectSourceContext.onResetValue can be used to unsubscribe.