# Document list (/ui/document-list)

## What it shows [#what-it-shows]

The files attached to a person or a role.

## Props [#props]

### DocumentUploadPanel [#documentuploadpanel]

| Prop | Type | What it does |
| --- | --- | --- |
| `title` | `ReactNode` | The section heading. Defaults to "Documents". |
| `count` | `number` | How many documents there are, as DocumentList takes it. The compact header shows it beside the title while it is above zero. |
| `loading` | `boolean` | A skeleton row in place of the list, and no count yet. |
| `error` | `ReactNode` | A failed load, upload or delete, above the drop zone. |
| `onFiles` (required) | `(files: File[]) => void \| Promise<void>` | Called with the files a person drops or picks; the host uploads them. |
| `uploading` | `boolean` | Shows the drop zone busy, with `labels.uploading`. |
| `accept` | `string` | The file types the picker offers, as the input's `accept`. |
| `kindSelect` | `DocumentKindSelect<TValue>` | Adds a select to the header for the kind the next upload is filed as. |
| `empty` | `CandidateEmptyCopy` | The blank slate's wording. Defaults to "No documents yet". |
| `density` | `DocumentListDensity` |   |
| `border` | `"none" \| "top" \| "bottom"` | The compact panel's divider, as the kit PanelSection takes it. Defaults to `bottom`. |
| `labels` | `Partial<DocumentUploadPanelLabels>` |   |
| `preview` | `DocumentPreviewProps` | Controlled document preview. The host owns URL loading, authorization and download callbacks. |
| `children` | `ReactNode` | The documents, usually DocumentListItems with the same `density`. |

### DocumentListItem [#documentlistitem]

| Prop | Type | What it does |
| --- | --- | --- |
| `name` (required) | `string` | The file name. It is the row's title and names each action for screen readers. |
| `kind` | `DocumentKind` | What kind of document this is, as a badge after the name. |
| `meta` | `ReactNode` | A muted line beside the kind, such as the size and when it was added. |
| `summary` | `ReactNode` | A short summary of what the document says, under the name. |
| `processing` | `boolean` | Still being read: a spinner and `labels.processing` stand in for a missing `summary`. |
| `onPreview` | `() => void` | Adds a preview button, such as for a file the host can show inline. |
| `onDownload` | `() => void \| Promise<unknown>` | Adds a download button. A returned promise shows a spinner until it settles. |
| `downloading` | `boolean` | Shows the download button's spinner, such as while another control downloads the file. |
| `onReanalyse` | `() => void \| Promise<unknown>` | Adds a re-analyse button. A returned promise shows a spinner until it settles. |
| `reanalysing` | `boolean` | Shows the re-analyse button's spinner. |
| `onDelete` | `() => void \| Promise<unknown>` | Adds a delete button, which asks to confirm in the row before calling this. A returned promise disables the confirm button until it settles. |
| `density` | `DocumentListDensity` |   |
| `labels` | `Partial<DocumentListItemLabels>` |   |

### DocumentList [#documentlist]

| Prop | Type | What it does |
| --- | --- | --- |
| `count` | `number` | How many documents there are. Zero shows the empty state in place of the rows. Left out, such as before the first load succeeds, the list shows only what `children` holds. |
| `loading` | `boolean` | A skeleton row in place of the list. |
| `empty` | `CandidateEmptyCopy` | The blank slate's wording. Defaults to "No documents yet". |
| `density` | `DocumentListDensity` |   |
| `children` | `ReactNode` | The documents, usually DocumentListItems with the same `density`. |

## Data it needs [#data-it-needs]

The component takes plain values and callbacks and keeps no records of its own. Pass it yours, from the Kith data layer or from a backend you already run.

## Copy to your agent [#copy-to-your-agent]

```text title="Copy to your agent"
Install RecruiterOS/recruit-ui and add a documents section with a drop zone and a row per file.
```