feat: add download_name parameter for custom download filenames

[Br1an67]

What

Add a download_name optional parameter to Element so developers can specify a human-readable filename for file downloads.

Closes #2124

Why

When using cl.Pdf with a file path, Chainlit persists the file with a UUID-based name. When users download the PDF from the browser's viewer, they get a UUID filename instead of the original name.

Changes

• backend/chainlit/element.py: Add download_name: Optional[str] = None to Element base class, pass it through persist_file()
• backend/chainlit/session.py: Accept and store download_name in the file dict
• backend/chainlit/server.py: Use download_name (falling back to name) in FileResponse with content_disposition_type="inline" to set the download filename while preserving inline display

Usage

pdf = cl.Pdf(
    name="My Report",
    path="./report.pdf",
    display="inline",
    download_name="UserFriendlyReport.pdf"
)

Without download_name, the element's name is used as the download filename (still better than the UUID).

Testing

Backward compatible — download_name defaults to None, falling back to existing name field.

---

Summary by cubic

Add a download_name option to Element so files (e.g., PDFs) download with a human-friendly filename while keeping inline viewing. The server sets an inline Content-Disposition and filename using download_name, falling back to name.

• New Features
  • Element.download_name optional field; serialized as downloadName, restored via to_dict/from_dict, persisted via persist_file, and added to FileDict.
  • File responses set inline Content-Disposition with filename from download_name (fallback to name).

^{Written for commit c15c275. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/chainlit/element.py">

<violation number="1" location="backend/chainlit/element.py:100">
P2: `download_name` was added to `Element`, but serialization/deserialization (`ElementDict`, `to_dict`, `from_dict`) was not updated, so custom download filenames will be dropped when elements are persisted or rehydrated.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

ci

[Br1an67]

Hi — just a gentle bump on this. Happy to make any changes if needed!