Component | File Drop

Render a file drop zone that allows users to upload files from the browser to your app.

Node.js
Python

import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

function onFiles(files: { buffer: Buffer, name: string, type: string }[]) {
    files.forEach(file => {
        const filePath = path.join(__dirname, file.name);

        // write to disk
        fs.writeFileSync(filePath, file.buffer);
    });
}

ui.fileDrop("pdf-file-drop", {
    label: "Drop files here",
    acceptedFileTypes: ["application/pdf"],
    onChange: onFiles
})

def on_files(files):
    print(files)

ui.file_drop(
    "pdf-file-drop",
    label="Drop files here",
    accepted_file_types=["application/pdf"],
    on_change=on_files
)

Learn more about file uploads.

API reference

Function signature

Node.js
Python

type ComposeFile = {
    buffer: Buffer;
    name: string;
    type: string;
}

ui.fileDrop(
    id: string,
    properties: Partial<{
        label: string,
        description: string,
        required: bool,
        validate: (value: ComposeFile[]) => string | void,
        onChange: (value: ComposeFile[]) => void,
        acceptedFileTypes: string[],
        minCount: int,
        maxCount: int,
        style: Style | null
    }>
)

class File(BytesIO):
    def __init__(self, content: bytes, file_name: str, file_type: str):
        super().__init__(content)
        self.name = file_name
        self.type = file_type

ui.file_drop(
    id: str,
    *,
    label: str = None,
    description: str = None,
    required: bool = True,
    validate: Callable[[File[]], str | None] = None,
    on_change: Callable[[File[]], None] = None,
    accepted_file_types: list[str] = None,
    min_count: int = 0,
    max_count: int = 1000000000,
    style: Style | None = None
)

Parameters

Node.js
Python

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Node.js
Python

properties.label

optional string

The label to display above the file drop. If not provided, the label will be inferred from the id.

label

optional str

The label to display above the file drop. If not provided, the label will be inferred from the id.

Node.js
Python

properties.description

optional string

A description to display between the label and file drop.

Node.js
Python

properties.required

optional boolean

Validate that the user has dropped at least one file before submitting the form it's part of or calling it's onChange hook. Defaults to true.

required

optional bool

Validate that the user has dropped at least one file before submitting the form it's part of or calling it's on_change hook. Defaults to True.

Node.js
Python

properties.validate

optional (files: ComposeFile[]) => string | void

Validate the file drop value before submitting it. If the function returns a string, it will be displayed as an error message.

The validator will be passed a list of files. Each file is an object with the following properties:

{
    buffer: Buffer;
    name: string;
    type: string;
}

validate

optional Callable[[File[]], str | None]

Validate the file drop value before submitting it. If the function returns a string, it will be displayed as an error message.

The validator will be passed a list of files. Each file is an instance of the File class with the following properties:

class File(BytesIO):
  def __init__(self, content: bytes, file_name: str, file_type: str):
      super().__init__(content)
      self.name = file_name
      self.type = file_type

Node.js
Python

properties.onChange

optional (files: ComposeFile[]) => void

A callback function that is called when the user changes the value of the file drop.

The callback will be passed a list of files. Each file is an object with the following properties:

{
    buffer: Buffer;
    name: string;
    type: string;
}

on_change

optional Callable[[File[]], None]

A callback function that is called when the user changes the value of the file drop.

The callback will be passed a list of files. Each file is an instance of the File class with the following properties:

class File(BytesIO):
  def __init__(self, content: bytes, file_name: str, file_type: str):
      super().__init__(content)
      self.name = file_name
      self.type = file_type

Node.js
Python

properties.acceptedFileTypes

optional string[]

A list of file types that the user can upload. Defaults to all file types.

The file types should be MIME type strings. For example, image/png or application/pdf. Learn more about MIME types here.

accepted_file_types

optional list[str]

A list of file types that the user can upload. Defaults to all file types.

The file types should be MIME type strings. For example, image/png or application/pdf. Learn more about MIME types here.

Node.js
Python

properties.minCount

optional number

Validate that the user has dropped at least some number of files. Defaults to 0.

Node.js
Python

properties.maxCount

optional number

Validate that the user has dropped at most some number of files. Defaults to 1000000000.

Node.js
Python

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.