Drop zone

ui.DropZone lights up when files are dragged over the window and receives them when they are dropped: on_drop gets each path and on_files the whole list. accept limits the types (["png", "jpg"], ["*.tar.gz"], ["folder"]) and files of other types go to on_reject. With browse=True (the default) a click opens the file dialog too. When a window has several zones, the one under the pointer gets the files, or else the one that accepts their type.

ui.DropZone · Category: System · Full reference →

Preview
Code

pz.row([
    ui.DropZone(text="Drop images here", hint="PNG or JPG, up to 10 MB", accept=["png", "jpg"],
                on_files=on_files),
    ui.DropZone(icon_name="file-spreadsheet", text="Import a CSV", accept=["csv"], multiple=False,
                show_files=True, files=["~/data/sales-2026.csv"], on_files=on_files),
], spacing=16, width=600)

When to use

For importing images, documents or data files, and attaching files to a message.
show_files=True lists what was dropped, with a button to remove each one; multiple=False keeps only the last file.
Dropped files also reach on_file_drop(path) of the window, for apps that don’t need a zone.

Usage

import pyzed as pz
from pyzed import ui

class Gallery(pz.App):
    def __init__(self):
        self.images = []

    def view(self):
        return pz.column([
            ui.DropZone(text="Drop photos", accept=["png", "jpg", "webp"],
                        on_files=lambda e: setattr(self, "images", list(e.value))),
            pz.row([pz.image(path, width=96, height=96) for path in self.images], spacing=8),
        ], spacing=12)

Variants

States

Drop zone: Files over it — Files over it

Drop zone: disabled=True — `disabled=True`

Files

Drop zone: browse=False — `browse=False`

Events

Drop zone has 5 events of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

It is a pz.Component, so it also raises on_mount and on_unmount, and its handlers get a pz.Event whose value holds the data.

Event	Handler gets	When
`on_drop`	`(event)`	Receives `event.value`: one dropped path (once per file).
`on_files`	`(event)`	Receives `event.value`: the list of files.
`on_reject`	`(event)`	Receives a path it does not accept.
`on_enter`	`(event)`	Files are dragged over the window.
`on_leave`	`(event)`	The drag left without dropping.

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

class Attach(pz.App):
    def __init__(self):
        self.files = []

    def received(self, event):           # on_files: event.value is every file so far
        self.files = list(event.value)

    def view(self):
        return pz.column([
            ui.DropZone(text="Drop files to attach", on_files=self.received),
            ui.label(f"{len(self.files)} files"),
        ], spacing=8, width=320)

from dataclasses import dataclass


@dataclass
class Dropped:
    path: str


class Attach(pz.App):
    files = ()

    def update(self, message):
        match message:
            case Dropped(path):
                self.files = (*self.files, path)

    def view(self):
        # on_drop runs once per file
        return ui.DropZone(accept=["png", "jpg"], on_drop=lambda e: Dropped(e.value))

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    rejected: str = ""


def view(state, set_state):
    return pz.column([
        ui.DropZone(text="Drop a CSV", accept=["csv"], multiple=False,
                    on_reject=lambda e: set_state(rejected=e.value)),
        ui.label(f"Not a CSV: {state.rejected}" if state.rejected else ""),
    ], spacing=8, width=320)

Tips

Properties and API

`ui.DropZone`

class DropZone

A component that takes files dragged from the system’s file manager and dropped on the window, and opens the file dialog on a click. It lights up while files are dragged over the window and keeps the dropped paths in files. The window’s on_file_drop hook hands each file to the zone under the pointer, else to one whose accept lists its type. See the Drop zone page.

Property	Default	Description
`text`	`""`	The main text (default: Drop files here).
`hint`	`""`	The line under it.
`icon_name`	`"upload"`	Its icon.
`accept`	`()`	Extensions (`["png", "jpg"]`), patterns (`"*.tar.gz"`) or `"folder"`; empty takes everything.
`multiple`	`True`	`False` keeps only the last file.
`browse`	`True`	A click opens the file dialog.
`show_files`	`False`	Lists the files under the text (each with an x).
`files`	`()`	The dropped paths.
`disabled`	`False`	Takes nothing.
`live`	`True`	`False` draws it without taking files (the designer’s canvas).

Events: on_drop, on_files, on_reject, on_enter, on_leave (events).

Full reference →

File pickerA path field with a button that opens the system's file or folder dialog.

CardA bordered surface with an optional title and actions.