# File Input
Choose, drop, or paste files, validate them, and submit them with a form.
A file input holds the files someone chooses, drops, or pastes, checks them against your rules, and submits them with a form. Uploading them to a server is up to your app.
```ts title="basic.ts"
import "@ui-sdk/web/file-input"
import { createElement, File as FileIcon, Upload, X } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
${createElement(Upload, { "aria-hidden": "true" }).outerHTML}
Drag and drop files here
Or paste them from your clipboard.
${createElement(FileIcon, { "aria-hidden": "true" }).outerHTML}
`
}
export { mount }
```
Browse Files or drop a few files on the zone, then remove one. Tab to the list to move between files with the arrow keys, and press Delete to remove the focused one.
## Installation
```bash
npm install @ui-sdk/web @ui-sdk/core
```
Import the component to register its elements. The import is safe on the server.
```ts
import "@ui-sdk/web/file-input"
```
## Composition
Use the following composition to build a `ui-file-input`:
```text
ui-file-input
├── ui-file-input-trigger
│ └── button
├── ui-file-input-dropzone
└── ui-file-input-list
└── template
└── ui-file-input-item
└── ui-file-input-item-remove
└── button
```
The trigger wraps a native button that opens the system file picker. The drop zone takes files that are dropped on it or pasted while focus is inside it; keep a trigger beside it for people using a keyboard. The list copies the item in its `` once for each file, and an item's `file` property holds its file; elements in the item with `data-file="name"`, `"size"`, `"type"` or `"path"` show that about the file. A remove button wraps a native button that removes its item's file.
## Usage
Import the parts and put them together:
```html
Drag and drop files here
```
## Upload Button
A trigger is enough when you only need the system file picker. Read the chosen file from the `valuechange` event to show its name beside the button.
```html
No file chosen
```
```ts
const input = document.querySelector("ui-file-input")!
input.addEventListener("valuechange", (event) => {
input.querySelector("span")!.textContent =
event.detail.value[0]?.name ?? "No file chosen"
})
```
## Accepted Types
`accept` takes MIME types, wildcards, and extensions, separated by commas, such as `image/*,.pdf`. It checks files from the picker, drops, and pastes. An extension matches the filename, even when the operating system reports an unexpected MIME type.
A rejected file never joins the value. The `reject` event's `detail.value` has each one with its `reasons`, such as `file-type`, so you can say why it was left out. While files are dragged over a drop zone, `data-drag-reject` shows when their types won't be accepted.
```html
```
```ts
input.addEventListener("reject", (event) => setRejected(event.detail.value))
```
## Limits
Use `max-files` to limit the total count, and `min-size` or `max-size` for bytes per file. When too many files arrive, the component accepts the first ones that pass the other checks until the list is full, and rejects the rest with `too-many-files`.
```html
```
## One File
Without `multiple`, a new file replaces the current one. A rejected file leaves the current value unchanged. With `multiple`, accepted files join the list.
```html
```
```ts
input.addEventListener("valuechange", (event) => {
input.querySelector("button")!.textContent = event.detail.value[0]
? "Replace PDF"
: "Choose a PDF"
})
```
## Validation
Set the `validate` property for checks of your own. Return a reason string to reject a file, or `null` to accept it. It runs after the built-in type and size checks, and its reason reaches the `reject` event like theirs. Validate uploads on your server too.
```ts
const input = document.querySelector("ui-file-input")!
input.validate = (file) =>
input.value.some((other) => other.name === file.name) ? "duplicate" : null
input.addEventListener("reject", (event) => setRejected(event.detail.value))
```
## File List
The list has one Tab stop. Arrow keys, Home, and End move between files; Delete or Backspace removes the focused file. Remove buttons are named for their file and stay outside the Tab order.
For an image preview, put an `` in the template, create an object URL from the item's `file` when the item is added, and revoke it when the item goes away:
```html
```
```ts
const list = document.querySelector("ui-file-input-list")!
new MutationObserver((records) => {
for (const { addedNodes, removedNodes } of records) {
for (const node of addedNodes) {
const image = (node as Element).querySelector?.("img")
const file = (node as HTMLElement & { file?: File }).file
if (image && file && !image.src) image.src = URL.createObjectURL(file)
}
for (const node of removedNodes) {
const image = (node as Element).querySelector?.("img")
if (image && !node.isConnected) URL.revokeObjectURL(image.src)
}
}
}).observe(list, { childList: true })
```
## Attachments
Put a textarea inside a drop zone to attach files to a message. `paste-target` takes file pastes from the textarea too, through a CSS selector; text pastes keep their normal behavior. It can also be `"document"`.
```html
```
## Page-Wide Drop
Set `target="document"` to take files dropped anywhere on the page. The zone shows `data-dragging` while a file is over the window, so it can be a full-page overlay. A drop on another zone stays with that zone.
```ts title="page.ts"
import "@ui-sdk/web/file-input"
import { createElement, File as FileIcon, Upload, X } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
${createElement(FileIcon, { "aria-hidden": "true" }).outerHTML}
`
}
export { mount }
```
Drag a file over this page to see the overlay, then drop it. The file joins the Attachments list; a drop on the first example's zone stays there.
While a drop zone is connected, dropping a file outside every zone doesn't navigate away from the page. Drops onto native file inputs and ordinary text drops keep their behavior.
## Folders
`directory` picks a whole folder and turns on `multiple`. Dropped folders are read recursively, up to 1,000 files, skipping system files such as `.DS_Store`. `data-file="path"` shows the path inside the folder, the same as `relativePath(file)` from `@ui-sdk/web/file-input`.
```html
```
## Camera
Use `capture="environment"` to request the rear camera, or `"user"` for the front camera. The picker offered depends on the device and browser; a desktop browser opens a file picker.
```html
```
## Controlled
Set the element's `value` property and listen for `valuechange`. `event.detail` has the files as `value`, the `reason`, and the `added`, `removed`, and `rejected` files. Call `event.preventDefault()` to keep the current value. The `reject` event reports rejected files even when none were accepted.
```ts
const input = document.querySelector("ui-file-input")!
input.value = files
input.addEventListener("valuechange", (event) => setFiles(event.detail.value))
```
## Opening from Anywhere
Create a controller with `createFileInputController()` and set it as the element's `controller` property. Use it to open the picker, add or remove files, clear the value, or read the files. Open the picker from a user action, such as a button press, so the browser allows it. The element's `api` property has the same methods. A `ui-file-input-trigger` outside the file input connects with `for` set to the file input's `id`.
```html
```
```ts
import { createFileInputController } from "@ui-sdk/web/file-input"
const attachments = createFileInputController()
document.querySelector("ui-file-input")!.controller = attachments
document
.querySelector('[data-action="open"]')!
.addEventListener("click", () => attachments.open())
document
.querySelector('[data-action="clear"]')!
.addEventListener("click", () => attachments.clear())
```
## Announcements
The component announces accepted, removed, and rejected files through a polite live region. Set the `announcement` property to change the message, or return `null` to skip it.
```ts
input.announcement = ({ added, removed }) =>
added.length
? `Added ${added.map((file) => file.name).join(", ")}.`
: removed.length
? `Removed ${removed.map((file) => file.name).join(", ")}.`
: null
```
## Forms
With `name`, the element submits its files through `ElementInternals` once it upgrades. A form reset returns to `defaultValue`, a property you set from script before connecting the element. `form` connects the file input to a form elsewhere on the page. Rejected files never submit, and `disabled` leaves the value out of the submission as well as stopping picks, drops, and pastes.
```html
```
```ts
input.defaultValue = [coverLetter]
```
## Fields
Wrap the file input in a [Field](/docs/web-components/components/field) to connect its label, description, and validation message. The trigger becomes the field's control, and pressing the label opens the picker. `required` stops the form from submitting with no file.
```html
Proof of addressA utility bill or bank statement from the last 3
months.Add a scan to continue.
```
## Custom Rendering
Parts have no render functions: each element is the part, and the trigger and remove parts wrap your own buttons. Give a part attributes of its own, like `role` and `aria-label` in place of a ``, and show content from its data attributes, like `in-data-drag-reject:inline` in Tailwind. The list's `` is the markup for each file:
```html
Images onlyRelease to addDrag images here
```
## Styling
Use `data-dragging`, `data-drag-accept`, and `data-drag-reject` on the drop zone to show what a drop would do. Drag acceptance reflects the file information the browser exposes before a drop. Inside a Field, the trigger also gets the field's attributes, such as `data-invalid`.
Each element has a `data-slot`, such as `file-input-dropzone`, and its state attributes are listed under [Data Attributes](#data-attributes).
## Data Attributes
### ``
`[data-slot="file-input"]`
- `data-disabled`: Present when disabled, by its own prop or a `