When to reach for FileCard, how the file name decides what it renders, and what to do in a list.
When to use
FileCard shows a file inside a conversation: one the reader attached to a message, or one the assistant produced. It gives the file a recognizable shape (type, name, size) or previews it when it is an image, a clip or a recording.
The file is part of a message, and the reader needs to tell at a glance what it is.
Several files go together, like the attachments of one message. That is FileCard.List.
Use something else when
The reader is choosing files to send. Attachments handles picking, dropping and uploading, and shows the files as cards.
The files are a long list to browse, sort or search. A Table or Listy fits that better than a row of cards.
The image is content, not an attachment. Use Image directly.
The name decides the card
The extension in name picks both the icon and the layout. report.pdf is a file card with a PDF icon, photo.jpg is an image preview, and clip.mp4 is a video player.
An image name with no src shows an empty preview. Until you have the URL, pass type="file" to show a file card, or set loading to show a spinner in the image's place.
A name with no extension, or one the card does not know, gets the default file icon. Pass icon with a preset name when you know the type from elsewhere, like a MIME type.
Long names are cut with an ellipsis, and the extension stays visible. Keep the full name somewhere the reader can get to it, like a tooltip or the download.
Images, audio and video
A media card is the preview and nothing else: no name, no size, no description.
Media cards ignore onClick, description and mask. Those apply to file cards only. An image already opens a larger preview on click. Configure it with imageProps.
loading works on images only. For a document that is still uploading, show the progress in description.
Audio and video use the browser's own player, so they look different in each browser. Pass a poster through videoProps so a video does not show a black frame.
Lists and removing files
FileCard.List keeps its own copy of items. A remove click takes the card out of that copy at once and then calls onRemove.
Remove the file from your state in onRemove. If you do not, the card disappears now and comes back the next time you pass items.
Pass a new array when files change. A list you change in place is not picked up.
Give every item a key. Without one, cards are keyed by name and position, so removing one card can animate the wrong one out.
Use removable as a function to keep some files fixed, like the ones already sent.
Overflow
wrap grows the list downward, which suits a message bubble. Inside a message input, where height is limited, use scrollX: one row with arrow buttons at the edges.
scrollY fits about one row of cards before it scrolls. Use it only where a short scrolling strip is what you want.
size="small" on the list makes every card smaller, which fits more files into an input.
Restyling it
Reach for the semantic keys before a descendant selector: root, file, icon, name and description on a card, plus card on the list.
The file-type colors are fixed per type (red for PDF, blue for Word, green for Excel). To match your palette, pass your own icon node.
To size image previews, set width and height on styles.file.