gr.UploadButton — the file picker that hides inside a button

$ import gradio as gr
import os

def intake_receipt(receipt):
    if receipt is None:
        return "No receipt uploaded yet."
    name = os.path.basename(receipt)
    size = os.path.getsize(receipt)
    return f"Queued {name} ({size} bytes) for expense claim processing."

with gr.Blocks(title="Expense intake") as demo:
    gr.Markdown("### Expense claim")
    rec = gr.UploadButton("Attach receipt photo", file_types=["image"],
                          type="filepath", variant="primary")
    out = gr.Textbox(label="status")
    rec.upload(intake_receipt, rec, out)

demo.launch()

* Running on local URL:  http://127.0.0.1:7931

Renders a gr.Blocks page: a Markdown heading '### Expense claim', then one UploadButton labelled 'Attach receipt photo' (variant='primary', so a filled blue button, native picker filtered to image/*), then a Textbox labelled 'status'. Config tree: id=1 markdown, id=2 uploadbutton, id=3 textbox; one dependency with targets=[[2,'upload']], inputs=[2], outputs=[3], api_name='intake_receipt'.
Handler received a NamedString path inside the server's file cache (/home/kmail/.hermes/cache/scratch/gradio/<hash>/receipt.png, 155 bytes for a tiny test PNG) and the app printed 'Queued receipt.png (155 bytes) for expense claim processing.' Driving the same endpoint with no file at all took the guard branch: 'No receipt uploaded yet.'
Tested with gradio 6.18.0.

os.path.basename() and os.path.getsize() work directly because the handler argument IS the path string. Guard for None anyway — an unguarded os.path.basename(None) is the most common crash in upload handlers.

$ import gradio as gr
import pandas as pd
import os

def summarise(files):
    if not files:
        return "no files"
    rows, total = [], 0
    for f in (files if isinstance(files, list) else [files]):
        df = pd.read_csv(f)
        rows.append(f"{os.path.basename(f)}: {len(df)} rows x {len(df.columns)} cols")
        total += len(df)
    return f"{len(rows)} tables, {total} rows total\n" + "\n".join(rows)

with gr.Blocks(title="Bulk CSV intake") as demo:
    gr.Markdown("### Monthly batch upload")
    with gr.Row():
        ub = gr.UploadButton("Add CSV exports", file_count="multiple",
                             file_types=[".csv", ".tsv"])
        ubd = gr.UploadButton("Add a whole folder", file_count="directory")
    out = gr.Textbox(label="batch summary", lines=6)
    ub.upload(summarise, ub, out)
    ubd.upload(summarise, ubd, out)

demo.launch()

* Running on local URL:  http://127.0.0.1:7932
/…/gradio/components/upload_button.py:93: UserWarning: The `file_types` parameter is ignored when `file_count` is 'directory'.

Renders a Row holding two UploadButtons side by side — 'Add CSV exports' (multi-file picker) and 'Add a whole folder' (directory picker) — above a 6-line Textbox labelled 'batch summary'. The two .upload listeners appear as two named endpoints, /summarise and /summarise_1.
Feeding two real CSVs (a.csv 3 data rows, b.csv 2 data rows) to either endpoint returned: '2 tables, 5 rows total'. The directory endpoint receives a LIST too, and via the API a bare single file is rejected before your code runs: pydantic ValidationError 'Input should be a valid list' for ListFiles.
Tested with gradio 6.18.0.

file_count='directory' returns list[str] exactly like 'multiple' — the only difference is which picker the browser opens. It warns at construction that file_types is ignored, so a folder button accepts everything in the folder.

$ import csv, os, tempfile
import gradio as gr

def make_template(n_rows):
    path = os.path.join(tempfile.mkdtemp(), "claim_template.csv")
    with open(path, "w", newline="") as fh:
        w = csv.writer(fh)
        w.writerow(["date", "vendor", "amount", "currency"])
        for _ in range(int(n_rows)):
            w.writerow(["", "", "", ""])
    return path

def check(f):
    if f is None:
        return "clicked the button but no file was chosen yet"
    return f"validating {os.path.basename(f)}"

with gr.Blocks(title="Template + validate") as demo:
    gr.Markdown("### Step 1: grab the template. Step 2: upload the filled one.")
    rows = gr.Slider(1, 10, value=3, step=1, label="blank rows")
    make = gr.UploadButton("Download claim template", variant="primary")
    make.click(make_template, rows, make)
    filled = gr.UploadButton("Upload your filled template", file_types=[".csv"])
    out = gr.Textbox(label="validation")
    filled.upload(check, filled, out)

demo.launch()

* Running on local URL:  http://127.0.0.1:7933

Renders: a Markdown step list, a Slider 'blank rows' (1–10, default 3), an UploadButton 'Download claim template', a second UploadButton 'Upload your filled template', and a Textbox 'validation'. Two dependencies: targets=[[4,'click']] with inputs=[slider] outputs=[uploadbutton], and targets=[[5,'upload']] with inputs=[5] outputs=[textbox].
Calling /make_template with n_rows=5 made the component serve a real generated file: /home/kmail/.hermes/cache/scratch/gradio/<hash>/claim_template.csv, returned to the caller as FileData with orig_name='claim_template.csv'. Calling /check with a real CSV returned 'validating a.csv'.
Tested with gradio 6.18.0.

Same instance is input and output: postprocess() wraps your path in FileData and the button turns into a download. Return a path string (or list of them) — postprocess runs Path(value).stat().st_size, so the file has to exist on disk when you return it.

$ # The half-working filter: file_types is only enforced for type='filepath'.
import os
import gradio as gr

def size_of(f):
    if isinstance(f, bytes):
        return f"GOT {len(f)} RAW BYTES (no filename, no extension check ran)"
    return f"GOT PATH {os.path.basename(f)}"

with gr.Blocks() as demo:
    a = gr.UploadButton("filepath, image only", type="filepath", file_types=["image"])
    b = gr.UploadButton("binary, image only", type="binary", file_types=["image"])
    o1, o2 = gr.Textbox(), gr.Textbox()
    a.upload(size_of, a, o1)
    b.upload(size_of, b, o2)

demo.launch()

* Running on local URL:  http://127.0.0.1:7934

Two UploadButtons stacked, both labelled 'image only', one filepath one binary, each feeding its own Textbox.
Same 31-byte a.csv pushed at both endpoints:
  filepath button -> gr.Error: "Invalid file type. Please upload a file that is one of these formats: ['image']" — rejected before the handler.
  binary button   -> GOT 31 RAW BYTES — the CSV sailed straight through into the function.
The same PNG through both: 'GOT PATH receipt.png' and 'GOT 155 RAW BYTES'.
Tested with gradio 6.18.0.

Reading the installed source confirms why: the extension check sits inside the if self.type == 'filepath' branch of _process_single_file(). The 'binary' branch just does open(path,'rb').read(). Keep type='filepath' if you rely on file_types as a server-side guard.