# File upload

> Single-file selection or multiple-file/folder intake with a drag-and-drop target, format guidance and accessible native picker.

- Group: Forms
- Status: stable
- Aliases: dropzone, upload
- HTML page: https://design.ipmnx.com/components/file-upload/
- Spec: https://design.ipmnx.com/design/#nx-file-upload

## Preview

**Knowledge source** Controlled file selection with a visible accepted-format hint.

```html
<div class="nx-upload">
  <label class="nx-upload__dropzone">
    <span class="nx-upload__icon" aria-hidden="true">
      <svg width="24" height="24" viewBox="0 0 24 24" fill="none"
          stroke="currentColor" stroke-width="2">
        <path d="M12 16V4m-4 4 4-4 4 4M4 16v4h16v-4"/>
      </svg>
    </span>
    <strong
        class="nx-upload__title">Choose a knowledge source</strong>
    <span class="nx-upload__hint">Drop a file here or browse</span>
    <span
        class="nx-upload__formats">PDF, TXT, MD · up to 25 MB</span>
    <input class="nx-upload__input" type="file"
        accept=".pdf,.txt,.md">
  </label>
</div>
```

```tsx
const [file, setFile] = useState<File | null>(null);
<NxFileUpload
  title="Choose a knowledge source"
  hint="Drop a file here or browse"
  formats="PDF, TXT, MD · up to 25 MB"
  accept=".pdf,.txt,.md"
  file={file}
  onFileChange={setFile}
  removeLabel="Remove selected file"
/>
```

## Variants

### Finished campaign media

NxFileDropzone collects files or a folder for review; applications enforce counts, formats and sizes before upload.

```html
<div class="nx-upload nx-file-dropzone">
  <label class="nx-upload__dropzone">
    <strong class="nx-upload__title">Choose campaign files</strong>
    <span class="nx-upload__hint">Drop images and videos here or
        choose multiple files</span>
    <span class="nx-upload__formats">Up to 30 files · 50 MB
        each</span>
    <input class="nx-upload__input" type="file" multiple
        accept="image/*,video/mp4">
  </label>
  <button class="nx-btn nx-btn--ghost"
      type="button">Choose folder</button>
</div>
```

```tsx
<NxFileDropzone
  title="Choose campaign files"
  hint="Drop images and videos here or choose multiple files"
  formats="Up to 30 files · 50 MB each"
  folderLabel="Choose folder"
  accept="image/*,video/mp4"
  onFiles={(files) => console.log(files.map(file => file.name))}
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` |   | yes | Primary picker instruction. |
| `hint` | `ReactNode` | `undefined` |   | Short drop/browse instruction. |
| `formats` | `ReactNode` | `undefined` |   | Accepted formats and size limit shown to users. |
| `file` | `File\|null` |   | yes | Controlled selected file. |
| `onFileChange` | `(file:File\|null)=>void` |   | yes | Receives picker, drop, and remove changes. |
| `removeLabel` | `string` |   | yes | Accessible name for the remove button. |
| `accept` | `string` | `undefined` |   | Native picker accept filter; server-side validation remains required. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-upload` | Stack wrapper |
| `.nx-upload__dropzone` | Dashed, accent-reactive picker target |
| `.nx-upload__input` | Visually hidden native file input |
| `.nx-upload__file` | Selected-file summary |
| `.nx-upload__remove` | Accessible remove action |

## States

### dragging

```html
<div class="nx-upload"><label class="nx-upload__dropzone nx-upload__dropzone--dragging"><strong class="nx-upload__title">Drop to upload</strong><input class="nx-upload__input" type="file"></label></div>
```

### disabled

```html
<div class="nx-upload"><label class="nx-upload__dropzone nx-upload__dropzone--disabled"><strong class="nx-upload__title">Uploads unavailable</strong><input class="nx-upload__input" type="file" disabled></label></div>
```

## Accessibility

- The native file input remains in the accessibility tree; :focus-within paints a visible focus ring around the whole drop target.
- Visible format and size guidance does not replace server-side type/size validation or a surfaced error message.

## Do / Don't

- Do: State accepted formats and the size limit before selection, then show the chosen filename and size.
- Don't make drag-and-drop the only path. Keep the native picker reachable by click and keyboard.

## Related

- [Field](https://design.ipmnx.com/components/field.md)
- [Alert](https://design.ipmnx.com/components/alert.md)

---

Source: registry.js (NX Design System)
