FileInput

File upload input widget for handling file uploads.

Examples

Basic Usage

This example runs a form with a single page containing the widget

Example Code

from abstra.forms import FileInput, run

# Create a page with the widget
example_page = [
    FileInput(label="File Input", key="my-file_input"),
]

# Run the form
result = run([example_page])

# Print the result
print(result)

Using the output of a FileInput

Runs a two-page form. The first page asks for a file and a filename; the second page persists the uploaded bytes to the persistent directory and sends a task with the saved path. New upload flows should prefer a Page, where the file bytes arrive in-memory via file["content"]. A Form's FileResponse re-materializes the upload lazily, so it grows less reliable the longer the read is deferred to later steps — persist the bytes in the step immediately after the upload page, as below.

Example Code

from pathlib import Path

from abstra.common import get_persistent_dir
from abstra.forms import FileInput, TextInput, run
from abstra.tasks import send_task

# Create a page to input a file and choose its filename
example_page = [
    TextInput(label="Choose a filename", key="filename"),
    FileInput(label="File input", key="my-file"),
]


# Persist the bytes in the step immediately after the upload page, then work only
# with the saved path — a FileResponse re-materializes lazily and grows unreliable
# the longer the read is deferred to later steps.
def save_inputed_file(state):
    inputted_file = state.get("my-file")
    custom_filename = state.get("filename")

    file_extension = Path(inputted_file.name).suffix
    dest = get_persistent_dir() / f"{custom_filename}{file_extension}"
    dest.write_bytes(inputted_file.content)

    # Send task with the persisted file path
    send_task("file", {"file_path": str(dest)})


# Run the form
result = run([example_page, save_inputed_file])

Parameters

Name	Description	Type	Default
label (required)	Text label displayed above the input.	str	None
key	Identifier for the widget, defaults to label if not provided.	str	None
required	Whether a file must be uploaded before proceeding.	bool	True
hint	Help text displayed below the input.	str	None
full_width	Whether the input should take up the full width of its container.	bool	False
disabled	Whether the input is non-interactive.	bool	False
max_file_size	Maximum file size in bytes.	int	None
multiple	Whether multiple files can be uploaded.	bool	False
min	Minimum number of files required when multiple=True.	int	None
max	Maximum number of files allowed when multiple=True.	int	None
accepted_formats	List of accepted file extensions.	List[str]	None
errors	Pre-defined validation error messages to display.	Union[List[str], str]	None

State Value

Union[FileResponse, List[FileResponse], None]: The uploaded file(s). FileResponse is a dictionary-like object: {'name': str, 'path': pathlib.Path}. If multiple is True, will be a list, otherwise a single FileResponse object.

info

This is the type of the value that this widget holds. It will show up when accessing widget's state item.

This also defines which value type can be used on initial_state