FileDrop

When to useLink to "When to use"

• Uploads, imports and attachments, especially where people may drag files from their desktop.

Use something else when:

• a single button is enough (a small toolbar action): a Button that opens a FileInputBase

UsageLink to "Usage"

import { FileDrop } from "@arshad-shah/cynosure";

<FileDrop multiple accept=".pdf,image/*" maxSize={5_000_000} hint="PDF or images, up to 5 MB" onFiles={upload} />

onFiles receives the files that passed. Without multiple only the first file is taken.

ChecksLink to "Checks"

accept (extensions, MIME types and type/*), maxSize (bytes) and maxFiles decide what is taken. Each refusal is listed in the zone and passed to onReject with its reason: type, size or count.

The whole windowLink to "The whole window"

With target="window", files dropped anywhere in the window are taken, for an app that opens whatever is dropped on it. An overlay covers the page while files are dragged in; text and links dragged over the page are left alone.

<FileDrop target="window" accept=".har,.json" onFiles={open} />

Your own picker and a list of chosen filesLink to "Your own picker and a list of chosen files"

onPick replaces the browser's file dialog with your own picker (Electron's dialog over IPC), as PathField's onPick does: the button calls it and is busy until it settles. It resolves with what was chosen, files or paths, or null when cancelled; a cancel or a failure changes nothing. Chosen files are checked like dropped ones and arrive in onFiles; chosen paths arrive in onPaths. Dropped files still arrive in onFiles.

value lists what has been chosen, files by name and paths as given, each with a remove button when onRemove is set. The list is yours: add to it from onPaths and onFiles, take out what onRemove(item, index) reports. A removal is announced, and focus moves to the next remove button, so several can be removed in a row.

const [chosen, setChosen] = useState<string[]>([]);

<FileDrop
  multiple
  value={chosen}
  onPick={() => window.api.pickFiles()} // Promise<string[] | null>
  onPaths={(paths) => setChosen([...chosen, ...paths])}
  onFiles={(files) => setChosen([...chosen, ...files.map((f) => f.name)])}
  onRemove={(_, index) => setChosen(chosen.filter((_, i) => i !== index))}
/>

value is display only: a form submits the files in the native input, those picked or dropped here.

FormsLink to "Forms"

With name, the form submits the accepted files, whether they were dropped or picked: FileDrop keeps its native file input in step.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• The button is the way in. Keyboard, touch and screen reader users pick files with it; dropping is a shortcut for pointer users. The native input is hidden and out of the tab order.
• Hint: read as the button's description.
• Chosen files: a list named by labels.files; each remove button is named "Remove " and the item's name, and the list's rows reverse in right-to-left text.
• Announcements: "2 files added" is announced politely; refusals are announced as an alert.
• Dragging: the zone lights up only for files (not dragged text or links) and says "Drop to add".
• Touch: the button's hit area is at least 44px on touch screens.
• Contrast: the prompt and hint keep 4.5:1 in light and dark modes.
• All built-in text is in labels.

ThemingLink to "Theming"

Tokens: --cy-file-drop-radius, --cy-file-drop-active-background, --cy-file-drop-overlay-background and --cy-file-drop-file-background (a chosen file's row).

RelatedLink to "Related"

FileInputBase · ProgressBar · Notice