File List
Last Updated: September 2026File lists render a collection of File Elements with shared remove, retry, and cancel handlers.
Source CodeAnatomy
link- 1Container
- 2File row
- 3Shared handlers
Variants
linkMixed statuses
Complete, uploading, and error items in one list.
All complete
Finished uploads ready for review or removal.
Uploading only
In-flight transfers with cancel.
Empty
files=[] returns null — nothing is rendered.
Usage Guidelines
linkWhen to use
- •To render a collection of uploaded files with shared remove/retry/cancel handlers.
- •Under a dropzone after the user selects multiple files.
- •When empty lists should render nothing.
When not to use
- •For a single file row — use File Element directly.
- •As the browse/drop affordance — use File Upload.
- •For non-file activity — use Activity Feed attachments.
Pair FileList with UploadTrigger so users can add and manage files.
Don't omit stable ids — handlers and React keys depend on FileItem.id.
Handle onRemove(id) to update your files array immutably.
Don't hand-roll borders for multiple rows — use FileList for shared chrome.
Behaviors
linkEmpty state
- •If files.length === 0, FileList returns null.
- •Render your own empty copy outside the list when needed.
Handlers
- •onRemove(id), onRetry(id), onCancel(id) wrap FileElement callbacks.
- •Omit a handler to hide that action on every row.
FileItem shape
- •id (required), fileName, optional fileSize / status / progress.
- •status mirrors FileElement: uploading | complete | error.
Content Guidelines
linkLists
- •Keep file names de-identified in demos and fixtures.
- •Order by recency or upload start so in-progress items stay visible.
Status copy
- •Let FileElement own per-row status text — don't duplicate “Complete” beside the list.
- •Summarize counts above the list (“3 of 4 uploaded”) when the list is long.
Accessibility
linkText & Labels
- •Each row inherits FileElement naming and action aria-labels.
- •Provide page-level context (“Uploaded files”) near the list.
ARIA attributes
- •Container is a div with visual grouping; rows are not a listbox.
- •Action buttons remain keyboard-focusable per row.
Keyboard Support
- •Tab through remove / retry / cancel controls across rows.
- •Enter / Space activates the focused IconButton.
WCAG Compliance Standards
FAQs
linkWhat happens with an empty files array?
FileList returns null — no border or empty shell is rendered.
How do callbacks work?
Pass onRemove / onRetry / onCancel; each is invoked with the FileItem id for that row.
FileList vs FileElement?
FileList is a bordered collection that maps FileItem[] to FileElement. Use FileElement alone for a custom layout.