File drop

Example

<div data-slean="file-drop">
	<input
		id="file-drop-upload"
		type="file"
		name="files"
		multiple
		accept="image/*,.pdf"
		aria-labelledby="file-drop-hint"
		aria-describedby="file-drop-files"
		data-slean-part="input"
	/>
	<p id="file-drop-hint">Drop images or PDFs here, or choose files</p>
	<output id="file-drop-files" for="file-drop-upload" data-slean-part="output"></output>
</div>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="file-drop".
	import '@svelte-lean/styles/file-drop.css';

	let files = $state<FileList | undefined>();
</script>

<form method="post" enctype="multipart/form-data">
	<div data-slean="file-drop">
		<input
			id="upload"
			type="file"
			name="files"
			multiple
			accept="image/*,.pdf"
			bind:files
			aria-labelledby="upload-hint"
			aria-describedby="upload-files"
			data-slean-part="input"
		/>
		<p id="upload-hint">Drop images or PDFs here, or choose files</p>
		<output id="upload-files" for="upload" data-slean-part="output"></output>
	</div>
	<button disabled={!files?.length}>Upload</button>
</form>

Why this implementation exists

A file input already accepts a dropped file: it becomes the input’s value and the input fires change, exactly as when the file is chosen in the picker. Drop-zone components rebuild that with dragover handlers, preventDefault() and a hidden input they fill by hand.

Here the input is the drop zone. The stylesheet stretches it, transparent, over the area, so a drop or a click anywhere on it reaches the input, and the form, the keyboard and the accessible name are unchanged. What a transparent input cannot do is show itself: the behavior marks the area while a file is dragged over it and writes the chosen names into an <output>, from three routed drag events and change. It never handles dragover, which fires continuously.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="file-drop"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/file-drop/register';

import '@svelte-lean/styles/file-drop.css';

Put the input, the instruction and an optional <output> in the root. Name the input with aria-labelledby pointing at the instruction, and describe it with the output.

Read the files from the input as usual: bind:files, FormData or a change listener. accept filters what the picker offers, not what can be dropped: check the type in your handler and on the server.

Anatomy

Runtime profile

The file drop registers dragenter, dragleave, drop and change handlers with the shared router, one listener per type for the whole page. A thousand areas keep one listener per type (tests/file-drop.test.ts).

Accessibility contract

• The input is the control: a native file input, named by the visible instruction and reached with Tab.
• Enter or Space opens the picker, which is the keyboard path; dropping is a pointer gesture with no keyboard equivalent.
• The output names the chosen files and is described by the input, so the choice is announced.
• The focus ring is drawn around the whole area while the input has keyboard focus.

Keyboard

Platform features

Without JavaScript

The input is shown as it is under @media (scripting: none): the platform's button and file name, a native drop target and the form value all work.

Server rendering

Render the markup with an empty output. Nothing is written before a drag or a change.

Before hydration

Before the behavior loads, a drop or a choice already sets the input's files; the names appear in the output from the next change on.

Styling

file-drop.css draws the dashed area, stretches the transparent input over it while scripting is enabled, marks the area during a drag (data-slean-dragging) and on :user-invalid, and moves the focus ring to the area. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :empty, :enabled, :focus-visible, :hover, :user-invalid.

Variant attributes: data-slean-dragging.

Compatibility notes

Dropping on a file input, the drag events and Intl.ListFormat are widely available; @media (scripting) is Baseline 2023. Uploading, previews, progress and removing single files are application code.

Testing

• packages/primitives/tests/file-drop.test.ts Vitest: the drag mark, disabled inputs, the list of names by language, 1000 roots
• apps/playground/tests/primitives/widgets.spec.ts Playwright: tooltip, toast, tree, range slider and number field in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/file-drop/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/file-drop/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/file-drop/behavior.ts the behavior definition
• packages/primitives/src/file-drop/register.ts the registration module
• packages/styles/css/file-drop.css the optional stylesheet