File Picker

A file picker component with drag-and-drop and validation.

vu-file-picker · @velkin/react-pro/file-picker

Copy page

Import

React

npm i @velkin/react-pro

import { LicenseInfo } from "@velkin/license";
// Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY
// Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY
LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? "");

// @velkin-pro
import { VuFilePicker } from "@velkin/react-pro/file-picker";

Examples

API

Props

Prop	Type	Default	Description
files	File[]	[]	Selected files in multiple mode. Default: `[]`.
file	`null \| File`	null	Selected file in single mode. Default: `null`.
multiple	`boolean`	false	Enables multiple file selection. Default: `false`.
accept	`string`	""	Comma-separated accepted extensions or wildcards. Default: `""`.
maxSize	`number`	15	Maximum file size in MB. Default: `15`.
errorMessage	`string`	""	Current picker validation error (type/size). Default: `""`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
showStructure	`boolean`	false	Shows selected files inline. Default: `false`.
showRemoveButtons	`boolean`	true	Shows remove control on each listed file. Default: `true`.
allowAllFiles	`boolean`	false	Skips extension filtering. Default: `false`.
droppable	`boolean`	false	Enables drag-and-drop selection. Default: `false`.
dragText	`string`	""	Dropzone placeholder; empty uses locale catalog. Default: `""`.
density	VuFilePickerDensity	"default"	Dropzone layout density (arrangement; not field `size`). Default: `"default"`.
icon	`"ion:cloud-upload"`	"ion:cloud-upload"	Dropzone icon name. Default: cloud upload icon.
buttonLabel	`string`	""	Trigger button label; empty uses locale catalog. Default: `""`.
directory	`boolean`	false	Enables directory picking mode. Default: `false`.
emitHandles	`boolean`	false	Includes file system handles in event detail. Default: `false`.
filepairId	`string`	""	Pairing id for linked file viewer. Default: `""`.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.
dragging	`boolean`	false	True while external files are dragged over the dropzone.

Events

Event	Detail	Description
vu-change	CustomEvent	When selected files change.
vu-invalid	VuFilePickerInvalidDetail	When validation fails or selection is cancelled.

Slots

Slot	Description
—	- Custom dropzone content.
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
field	Column that stacks dropzone, optional file list, and error.
dropzone	Outer drop area container.
drop-content	Inner dropzone content wrapper.
drop-icon	Icon container inside the dropzone.
drop-placeholder	Empty-state placeholder text.
file-picker-button	Browse or select-folder trigger button.
drop-overlay	Full-surface overlay during drag-over.
file-structure	Wrapper for the optional file list.
file-list	List of selected file names.
file-item	One selected file row.
file-name	File name text in the structure list.
file-remove	Remove control for one listed file.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.

Methods

Method	Description
validateInput	- Runs validators and syncs validity.
openFilePicker	- Opens file or directory picker based on directory mode.
clear	- Clears current selection and emits `vu-change`.
removeFileAt	- Removes one selected file by index.
removeFile	- Removes one selected file by reference.
dispatchError	- Emits `vu-invalid` and updates error state.

Types

Name	Definition
CustomEvent	`VuFilePickerSelectedSingleDetail \| VuFilePickerSelectedMultiDetail`
File \| null	`null \| File`
VuFilePickerDensity	`"default" \| "compact" \| "comfortable"`
VuFilePickerInvalidDetail	`{ error: string; }`

Import

React

npm i @velkin/react-pro import { LicenseInfo } from "@velkin/license"; // Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY // Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? ""); // @velkin-pro import { VuFilePicker } from "@velkin/react-pro/file-picker";

API

Props

Prop	Type	Default	Description
files	File[]	[]	Selected files in multiple mode. Default: `[]`.
file	`null \| File`	null	Selected file in single mode. Default: `null`.
multiple	`boolean`	false	Enables multiple file selection. Default: `false`.
accept	`string`	""	Comma-separated accepted extensions or wildcards. Default: `""`.
maxSize	`number`	15	Maximum file size in MB. Default: `15`.
errorMessage	`string`	""	Current picker validation error (type/size). Default: `""`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
showStructure	`boolean`	false	Shows selected files inline. Default: `false`.
showRemoveButtons	`boolean`	true	Shows remove control on each listed file. Default: `true`.
allowAllFiles	`boolean`	false	Skips extension filtering. Default: `false`.
droppable	`boolean`	false	Enables drag-and-drop selection. Default: `false`.
dragText	`string`	""	Dropzone placeholder; empty uses locale catalog. Default: `""`.
density	VuFilePickerDensity	"default"	Dropzone layout density (arrangement; not field `size`). Default: `"default"`.
icon	`"ion:cloud-upload"`	"ion:cloud-upload"	Dropzone icon name. Default: cloud upload icon.
buttonLabel	`string`	""	Trigger button label; empty uses locale catalog. Default: `""`.
directory	`boolean`	false	Enables directory picking mode. Default: `false`.
emitHandles	`boolean`	false	Includes file system handles in event detail. Default: `false`.
filepairId	`string`	""	Pairing id for linked file viewer. Default: `""`.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.
dragging	`boolean`	false	True while external files are dragged over the dropzone.

Events

Event	Detail	Description
vu-change	CustomEvent	When selected files change.
vu-invalid	VuFilePickerInvalidDetail	When validation fails or selection is cancelled.

Slots

Slot	Description
—	- Custom dropzone content.
error	Replaces default validation message list when assigned.

CSS parts

Part	Description
field	Column that stacks dropzone, optional file list, and error.
dropzone	Outer drop area container.
drop-content	Inner dropzone content wrapper.
drop-icon	Icon container inside the dropzone.
drop-placeholder	Empty-state placeholder text.
file-picker-button	Browse or select-folder trigger button.
drop-overlay	Full-surface overlay during drag-over.
file-structure	Wrapper for the optional file list.
file-list	List of selected file names.
file-item	One selected file row.
file-name	File name text in the structure list.
file-remove	Remove control for one listed file.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.

Methods

Method	Description
validateInput	- Runs validators and syncs validity.
openFilePicker	- Opens file or directory picker based on directory mode.
clear	- Clears current selection and emits `vu-change`.
removeFileAt	- Removes one selected file by index.
removeFile	- Removes one selected file by reference.
dispatchError	- Emits `vu-invalid` and updates error state.

Types

Name	Definition
CustomEvent	`VuFilePickerSelectedSingleDetail \| VuFilePickerSelectedMultiDetail`
File \| null	`null \| File`
VuFilePickerDensity	`"default" \| "compact" \| "comfortable"`
VuFilePickerInvalidDetail	`{ error: string; }`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse