Chat - Attachments

Let users attach files to chat messages with MIME-type, size, and count validation.

The attach button opens the browser file picker. Selected files are queued as draft attachments and previewed in the composer area before the message is sent.

Playground

The demos below let you tune the attach button and the pending-attachment list: The attachment-list playground seeds draft attachments directly into the chat store so that every status can be previewed without uploading files — in an app, attachments are added through the file picker or addAttachment().

Disabling attachments

Attachments are enabled by default. To hide the attach button entirely, set the attachments feature flag to false:

<ChatBox adapter={adapter} features={{ attachments: false }} />

Validating attachments

Pass a configuration object to the attachments feature flag to control which files are accepted:

<ChatBox
  adapter={adapter}
  features={{
    attachments: {
      acceptedMimeTypes: ['image/*', 'application/pdf'],
      maxFileCount: 5,
      maxFileSize: 10 * 1024 * 1024, // 10 MB
      onAttachmentReject: (rejections) => {
        rejections.forEach(({ file, reason }) => {
          console.warn(`Rejected ${file.name}: ${reason}`);
        });
      },
    },
  }}
/>

Try attaching a file that is not an image or PDF, or one larger than 500 KB:

Attachments configuration reference

Rejection reasons

When a file is rejected, the ChatAttachmentRejection object contains:

Draft attachment lifecycle

Each file goes through a status lifecycle as it moves from selection to submission:

queued  -->  uploading  -->  uploaded  -->  (sent with message)
                  \
                   -->  error

Draft attachment type reference

For image files, previewUrl is an object URL that the composer creates and revokes automatically — when the attachment is removed, after the message that references it is removed, or on unmount. Don't call URL.revokeObjectURL() on it yourself.

Managing attachments programmatically

Most apps only need the features configuration above. Reach for the useChatComposer() hook when you're building a custom attachment UI outside the built-in composer:

import { useChatComposer } from '@mui/x-chat/headless';

function AttachmentManager() {
  const composer = useChatComposer();

  return (
    <div>
      <p>Attachments: {composer.attachments.length}</p>
      <ul>
        {composer.attachments.map((att) => (
          <li key={att.localId}>
            {att.file.name} ({att.status})
            <button onClick={() => composer.removeAttachment(att.localId)}>
              Remove
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}

The table below covers the attachment-related members. See the Composer page for the complete useChatComposer() reference.

Sending attachments through the adapter

On submit, the runtime hands the queued attachments to your adapter's sendMessage() method — this is where files actually leave the browser:

async sendMessage({ message, attachments, signal }) {
  const formData = new FormData();
  formData.append('message', JSON.stringify(message));
  attachments?.forEach((att) => {
    formData.append('files', att.file);
  });

  const res = await fetch('/api/chat', {
    method: 'POST',
    body: formData,
    signal,
  });
  return res.body!;
},

See also

• Composer for the full Composer reference.
• Adapter for details on how attachments flow through sendMessage().

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <ChatComposerAttachButton />