FileUpload API

API documentation for FileUpload component

FileUploadRoot#

Props#

Defines valid properties in FileUpload component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: FileUploadRootInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: FileUploadRootInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<FileUploadRootPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: FileUploadRootInstance) => ReactNode)	null	The children to render.
name	string	null	Name of the request parameter to identify the files at backend.
url	string	null	Remote url to upload the files.
multiple	boolean	false	Used to select multiple files at once from file dialog.
accept	string	null	Pattern to restrict the allowed file types such as "image/*".
disabled	boolean	false	When present, it specifies that the element should be disabled.
auto	boolean	false	When enabled, upload begins automatically after selection is completed.
maxFileSize	number	null	Maximum file size allowed in bytes.
fileLimit	number	null	Maximum number of files that can be uploaded.
withCredentials	boolean	false	Cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates.
customUpload	boolean	false	Whether to use the default upload or a manual implementation defined in uploadHandler callback.
invalidFileLimitMessage	string	'Maximum number of files exceeded, limit is {0} at most.'	Message to display when number of files to be uploaded exceeds the limit.
invalidFileSizeMessage	string	'{0}: Invalid file size, file size should be smaller than {1}.'	Message to display when file size exceeds the limit.
invalidFileTypeMessage	string	'{0}: Invalid file type, allowed file types: {1}.'	Message to display when file type is not allowed.
uploadHandler	(event: FileUploadHandlerEvent) => void	null	Callback to invoke to implement a custom upload.
onSelect	(event: FileUploadSelectEvent) => void	null	Callback to invoke when files are selected.
onBeforeUpload	(event: FileUploadBeforeUploadEvent) => void	null	Callback to invoke before file upload begins to customize the request such as post parameters before the files.
onUpload	(event: FileUploadUploadEvent) => void	null	Callback to invoke when file upload is complete.
onError	(event: FileUploadErrorEvent) => void	null	Callback to invoke if file upload fails.
onProgress	(event: FileUploadProgressEvent) => void	null	Callback to invoke on upload progress.
onBeforeSend	(event: FileUploadBeforeSendEvent) => void	null	Callback to invoke before send for customization such as adding headers.
onClear	() => void	null	Callback to invoke when files in queue are removed without uploading.
onRemove	(event: FileUploadRemoveEvent) => void	null	Callback to invoke when a file is removed.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Defines valid state in FileUpload component.

name	type	default	description
files	File[]	null	List of currently selected files to be uploaded.
messages	string[]	null	Validation or error messages.
progress	number	null	Current upload progress as a percentage (0-100).
uploadedFiles	File[]	null	List of successfully uploaded files.

Exposes#

Defines the methods and properties exposed by FileUpload component.

name	type	default	description
state	useFileUploadState	null	State of the file upload.
uploadedFileCount	{ current: number }	null	Reference to track the number of uploaded files for file limit validation.
hasFiles	boolean	null	Indicates whether there are files selected for upload.
hasUploadedFiles	boolean	null	Indicates whether there are files that have been successfully uploaded.
inputRef	RefObject<HTMLInputElement>	null	Reference to the file input element.
contentRef	RefObject<HTMLDivElement>	null	Reference to the content element for drag and drop support.
upload	() => void	null	Initiates the upload process for selected files.
choose	() => void	null	Programmatically triggers the file selection dialog.
clear	() => void	null	Clears all selected files and messages.
remove	(index: number) => void	null	Removes a file from the selected files list by index.
removeUploadedFile	(index: number) => void	null	Removes a file from the uploaded files list by index.
formatSize	(bytes: number) => string	null	Formats a file size in bytes to a human-readable string.
onFileSelect	(event: ChangeEvent<HTMLInputElement>) => void	null	Handler for file selection from input or drag-and-drop.
onDragEnter	(event: DragEvent) => void	null	Handler for drag enter event.
onDragOver	(event: DragEvent) => void	null	Handler for drag over event.
onDragLeave	() => void	null	Handler for drag leave event.
onDrop	(event: DragEvent) => void	null	Handler for drop event.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of FileUpload component.

name	type	default	description
root	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.
content	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the content's DOM element.
fileList	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file list's DOM element.
file	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file's DOM element.
fileThumbnail	FileUploadRootPassThroughType<HTMLAttributes<HTMLImageElement>>	null	Used to pass attributes to the file thumbnail's DOM element.
fileInfo	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file info's DOM element.
fileName	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the fileName's DOM element.
fileSize	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the fileSize's DOM element.
fileActions	FileUploadRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file actions' DOM element.

Types#

Instance

Instance of FileUpload component.

values
ComponentInstance<FileUploadRootProps, FileUploadRootState, FileUploadRootExposes>

FileUploadContent#

Props#

Defines valid properties in FileUploadContent component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: FileUploadContentInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: FileUploadContentInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<FileUploadContentPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: FileUploadContentInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Exposes#

Defines the methods and properties exposed by FileUploadContent component.

name	type	default	description
fileupload	FileUploadRootInstance	null	Instance of the FileUpload component.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of FileUploadContent component.

name	type	default	description
root	FileUploadContentPassThroughType<HTMLAttributes<HTMLButtonElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of FileUploadContent component.

values
ComponentInstance<FileUploadContentProps, FileUploadContentState, FileUploadContentExposes>

FileUploadList#

Props#

Defines valid properties in FileUploadList component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: FileUploadListInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: FileUploadListInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<FileUploadListPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: FileUploadListInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Exposes#

Defines the methods and properties exposed by FileUploadList component.

name	type	default	description
fileupload	FileUploadRootInstance	null	Instance of the FileUpload component.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of FileUploadList component.

name	type	default	description
root	FileUploadListPassThroughType<HTMLAttributes<HTMLButtonElement>>	null	Used to pass attributes to the root's DOM element.
fileList	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file list's DOM element.
file	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file's DOM element.
fileThumbnail	FileUploadListPassThroughType<HTMLAttributes<HTMLImageElement>>	null	Used to pass attributes to the file thumbnail's DOM element.
fileInfo	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file info's DOM element.
fileName	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the fileName's DOM element.
fileSize	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the fileSize's DOM element.
fileActions	FileUploadListPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the file actions' DOM element.

Types#

Instance

Instance of FileUploadList component.

values
ComponentInstance<FileUploadListProps, FileUploadListState, FileUploadListExposes>

useFileUpload#

Props#

Defines valid properties in useFileUpload.

name	type	default	description
name	string	null	Name of the request parameter to identify the files at backend.
url	string	null	Remote url to upload the files.
multiple	boolean	false	Used to select multiple files at once from file dialog.
accept	string	null	Pattern to restrict the allowed file types such as "image/*".
disabled	boolean	false	When present, it specifies that the element should be disabled.
auto	boolean	false	When enabled, upload begins automatically after selection is completed.
maxFileSize	number	null	Maximum file size allowed in bytes.
fileLimit	number	null	Maximum number of files that can be uploaded.
withCredentials	boolean	false	Cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates.
customUpload	boolean	false	Whether to use the default upload or a manual implementation defined in uploadHandler callback.
invalidFileLimitMessage	string	'Maximum number of files exceeded, limit is {0} at most.'	Message to display when number of files to be uploaded exceeds the limit.
invalidFileSizeMessage	string	'{0}: Invalid file size, file size should be smaller than {1}.'	Message to display when file size exceeds the limit.
invalidFileTypeMessage	string	'{0}: Invalid file type, allowed file types: {1}.'	Message to display when file type is not allowed.
uploadHandler	(event: FileUploadHandlerEvent) => void	null	Callback to invoke to implement a custom upload.
onSelect	(event: FileUploadSelectEvent) => void	null	Callback to invoke when files are selected.
onBeforeUpload	(event: FileUploadBeforeUploadEvent) => void	null	Callback to invoke before file upload begins to customize the request such as post parameters before the files.
onUpload	(event: FileUploadUploadEvent) => void	null	Callback to invoke when file upload is complete.
onError	(event: FileUploadErrorEvent) => void	null	Callback to invoke if file upload fails.
onProgress	(event: FileUploadProgressEvent) => void	null	Callback to invoke on upload progress.
onBeforeSend	(event: FileUploadBeforeSendEvent) => void	null	Callback to invoke before send for customization such as adding headers.
onClear	() => void	null	Callback to invoke when files in queue are removed without uploading.
onRemove	(event: FileUploadRemoveEvent) => void	null	Callback to invoke when a file is removed.

State#

Defines valid state in useFileUpload.

name	type	default	description
files	File[]	null	List of currently selected files to be uploaded.
messages	string[]	null	Validation or error messages.
progress	number	null	Current upload progress as a percentage (0-100).
uploadedFiles	File[]	null	List of successfully uploaded files.

Exposes#

Defines the methods and properties exposed by useFileUpload.

name	type	default	description
state	useFileUploadState	null	State of the file upload.
uploadedFileCount	{ current: number }	null	Reference to track the number of uploaded files for file limit validation.
hasFiles	boolean	null	Indicates whether there are files selected for upload.
hasUploadedFiles	boolean	null	Indicates whether there are files that have been successfully uploaded.
inputRef	RefObject<HTMLInputElement>	null	Reference to the file input element.
contentRef	RefObject<HTMLDivElement>	null	Reference to the content element for drag and drop support.
upload	() => void	null	Initiates the upload process for selected files.
choose	() => void	null	Programmatically triggers the file selection dialog.
clear	() => void	null	Clears all selected files and messages.
remove	(index: number) => void	null	Removes a file from the selected files list by index.
removeUploadedFile	(index: number) => void	null	Removes a file from the uploaded files list by index.
formatSize	(bytes: number) => string	null	Formats a file size in bytes to a human-readable string.
onFileSelect	(event: ChangeEvent<HTMLInputElement>) => void	null	Handler for file selection from input or drag-and-drop.
onDragEnter	(event: DragEvent) => void	null	Handler for drag enter event.
onDragOver	(event: DragEvent) => void	null	Handler for drag over event.
onDragLeave	() => void	null	Handler for drag leave event.
onDrop	(event: DragEvent) => void	null	Handler for drop event.

Events#

FileUploadHandlerEvent

Custom upload handler event

name	type	description
files	File[]	List of files to be uploaded.
options	{ clear: () => void; props: useFileUploadProps }	Options object containing utility methods and component properties.

FileUploadSelectEvent

Custom file select event.

name	type	description
originalEvent	ChangeEvent<HTMLInputElement, Element> \| DragEvent	Original browser event.
files	File[]	List of selected files.

FileUploadRemoveEvent

Custom file remove event.

name	type	description
file	File	Removed file.

FileUploadBeforeUploadEvent

Custom before upload event.

name	type	description
xhr	XMLHttpRequest	XmlHttpRequest instance.
files	File[]	Files to be uploaded.

FileUploadUploadEvent

Custom upload event.

name	type	description
xhr	XMLHttpRequest	XmlHttpRequest instance.
files	File[]	Uploaded files.

FileUploadErrorEvent

Custom error event.

name	type	description
xhr	XMLHttpRequest	XmlHttpRequest instance.
files	File[]	Files that failed to upload.

FileUploadProgressEvent

Custom progress event.

name	type	description
originalEvent	ProgressEvent	Original browser event.
progress	number	Calculated progress value.

FileUploadBeforeSendEvent

Custom before send event.

name	type	description
xhr	XMLHttpRequest	XmlHttpRequest instance.
formData	FormData	FormData object.

Types#

Instance

Instance of useFileUpload headless.

values
HeadlessInstance<useFileUploadProps, useFileUploadState, useFileUploadExposes>