File field

Example

<label for="file-field-attachments">Attachments</label>
<input
	id="file-field-attachments"
	type="file"
	name="attachments"
	data-slean="file-field"
	accept="image/*,.pdf"
	multiple
	aria-describedby="file-field-attachments-hint"
/>
<p id="file-field-attachments-hint">Images or PDF files.</p>

<script lang="ts">
	// Nothing to import: the browser owns the field. The stylesheet is optional.
	import '@svelte-lean/styles/file-field.css';
</script>

<label for="file-field-attachments">Attachments</label>
<input
	id="file-field-attachments"
	type="file"
	name="attachments"
	data-slean="file-field"
	accept="image/*,.pdf"
	multiple
	aria-describedby="file-field-attachments-hint"
/>
<p id="file-field-attachments-hint">Images or PDF files.</p>

Why this implementation exists

A common file control hides the input and styles a label as its button. It then has to rebuild what the input showed: the chosen file names, the focus ring and the keyboard path, usually with a script that reads files on every change.

::file-selector-button styles the input’s own button instead. The input stays visible, focusable and labelled, and the browser keeps showing what was chosen.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

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

Give the input a name and submit it in a form with method="post" and enctype="multipart/form-data", or read its files in the application.

accept filters the chooser by MIME type or extension. It is not validation, since the chooser can show all files: check the type on the server. multiple allows several files; capture asks a mobile browser for the camera.

Anatomy

Runtime profile

Tier 0: the field has no behavior module, and the Vite plugin maps file-field to no module. Choosing, filtering and submitting are the browser’s.

Accessibility contract

• A label through <label for>; accepted types and limits through aria-describedby.
• The input is one tab stop; Enter or Space opens the chooser, which belongs to the operating system.
• The focus ring is the shared one, drawn around the whole field.
• :user-invalid marks a required field left empty only after the user interacted with it.

Keyboard

Platform features

Without JavaScript

Fully functional: choosing files and submitting them with a form need no script.

Server rendering

Static HTML. A file input cannot have an initial value; the server renders it empty.

Before hydration

Nothing is attached; the field works before and after hydration alike.

Styling

file-field.css draws the box at the control height of the other fields, styles ::file-selector-button as a quiet button inside it and grows both on coarse pointers. The button label and the file name text cannot be replaced from CSS. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: ::file-selector-button, :disabled, :focus-visible, :hover, :user-invalid, [aria-invalid="true"].

Variant attributes: data-status (warning, error).

Controlled integration

The chosen files are the input’s files. bind:files gives the application the FileList to list, preview or upload; the field renders nothing beyond the browser’s summary.

<script lang="ts">
	let files = $state<FileList>();
</script>

<input id="file-field-attachments" type="file" name="attachments" data-slean="file-field"
	multiple bind:files />

{#if files?.length}
	<ul>
		{#each files as file (file.name)}
			<li>{file.name}</li>
		{/each}
	</ul>
{/if}

Compatibility notes

::file-selector-button is Baseline 2021; where it is missing, the browser’s own button appears inside the styled box. The package adds no drop zone: dropping a file onto the input itself is the browser’s behavior where it exists, and a larger drop area needs dragover and drop listeners, which this Tier 0 primitive does not ship.

Examples

Camera

capture asks a mobile browser to open the camera instead of the chooser; environment is the rear camera, user the front one. Desktop browsers ignore it and open the file chooser.

<!-- On a phone, capture offers the camera directly; desktop browsers open the chooser. -->
<label for="file-field-receipt">Receipt photo</label>
<input
	id="file-field-receipt"
	type="file"
	name="receipt"
	data-slean="file-field"
	accept="image/*"
	capture="environment"
/>

Testing

• apps/playground/tests/primitives/inputs-overlays.spec.ts Playwright, with page JavaScript enabled and disabled, and axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

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