KQ-1165 · FOLDER/DROP

Folder Drop

A file field drawn as a paper folder: files dragged over it open its mouth, the front flap tipping toward you on the snap spring, and each accepted file falls in as a sheet of paper behind the flap on a cascade, after which the flap shuts and the folder lands on the recoil spring. A file it will not take, the wrong type, over `maxSize`, a duplicate or one too many, falls onto the shut edge, jumps and tumbles away and is listed with the reason, while every filed file gets a row whose swallowtail progress ribbon follows the host's upload progress on the glide spring. The folder is a real button over a real file input, so click, Enter or Space open the system picker and the picked files go through the same checks and the same fall.

KQ-1165 · FOLDER/DROP

Next: gate-west.jpg

2 files · 1 uploading

Open it on the Atelier stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/folder-drop

Props

value / defaultValue: FolderDropItem[]; default []; The files in the folder: `{ id, name, size, type?, progress?, file? }`. Controlled or uncontrolled; the host owns `progress`, and files it adds itself fall in silently.
onValueChange: (items: FolderDropItem[]) => void; default —; Fires from the drop, pick or removal that changed the list.
onReject: (rejections: { name: string; reason: string }[]) => void; default —; The files that bounced off a drop or pick, with the reason for each.
label: string; default —; The field's visible label; with "Choose files" it names the folder button.
name: string; default —; Form field name for the real file input, whose files are rebuilt from the list after every change.
hint: string; default —; Guidance under the folder. Defaults to what it takes and how large, such as "Images up to 10 MB."
error: string; default —; An error from the host, shown under the folder and announced once.
required: boolean; default false; The form needs at least one file; set on the file input while the folder is empty.
disabled: boolean; default false; Refuses drops and picks and dims the field.
maxSize: number; default 10; The largest file it takes, in MB; a larger one bounces with its size and the limit.
accept: "images" | "docs" | "any"; default "any"; Which files it takes; also sets the picker's filter and the default hint.
folder: "manila" | "blue" | "kraft"; default "manila"; The folder's paper, the same in either theme.
maxFiles: number; default 8; How many files the folder holds; the rest of a drop bounces.
sound: boolean; default false; A swish as sheets go in, a thud as the flap shuts and a shrug for each bounce. Only ever in answer to the visitor.
className: string; default —; Classes for the field's root.

Prop	Type	Default	Description
value / defaultValue	FolderDropItem[]	[]	The files in the folder: `{ id, name, size, type?, progress?, file? }`. Controlled or uncontrolled; the host owns `progress`, and files it adds itself fall in silently.
onValueChange	(items: FolderDropItem[]) => void	—	Fires from the drop, pick or removal that changed the list.
onReject	(rejections: { name: string; reason: string }[]) => void	—	The files that bounced off a drop or pick, with the reason for each.
label	string	—	The field's visible label; with "Choose files" it names the folder button.
name	string	—	Form field name for the real file input, whose files are rebuilt from the list after every change.
hint	string	—	Guidance under the folder. Defaults to what it takes and how large, such as "Images up to 10 MB."
error	string	—	An error from the host, shown under the folder and announced once.
required	boolean	false	The form needs at least one file; set on the file input while the folder is empty.
disabled	boolean	false	Refuses drops and picks and dims the field.
maxSize	number	10	The largest file it takes, in MB; a larger one bounces with its size and the limit.
accept	"images" \| "docs" \| "any"	"any"	Which files it takes; also sets the picker's filter and the default hint.
folder	"manila" \| "blue" \| "kraft"	"manila"	The folder's paper, the same in either theme.
maxFiles	number	8	How many files the folder holds; the rest of a drop bounces.
sound	boolean	false	A swish as sheets go in, a thud as the flap shuts and a shrug for each bounce. Only ever in answer to the visitor.
className	string	—	Classes for the field's root.