bug: FilePicker and TextField initialization errors in v0.84.0 (macOS) - TypeError and Unknown control issues on Mac OS 26

[AlessioForconi]

Duplicate Check

• I have searched the opened issues and there are no duplicates

Describe the bug

Environment:
​Flet Version: 0.84.0
​Python Version: 3.14.0 (pre-release/dev)
​OS: macOS (Apple Silicon)
​Context: Desktop App
​Issue 1: TypeError on basic control initialization
When following the official documentation for version 0.84.0, common keyword arguments are causing TypeError, suggesting they have been removed or renamed in the constructor without being updated in the docs.
​FilePicker: ft.FilePicker(on_result=...) throws TypeError: FilePicker.init() got an unexpected keyword argument 'on_result'
​TextField: ft.TextField(placeholder=...) throws TypeError: TextField.init() got an unexpected keyword argument 'placeholder' (even though label works).
​Issue 2: "Unknown control" error in UI
If I bypass the TypeError by initializing the control empty and assigning the handler as a property (e.g., fp.on_result = handler), the application starts but the UI displays a red box with "Unknown control: FilePicker".
​This happens even when the control is correctly added to page.overlay.
​On macOS, attempting to trigger the FilePicker in this state often results in an application hang (spinning pinwheel).
​Steps to reproduce:
​Use Flet v0.84.0.
​Attempt to create a FilePicker with an on_result handler.
​Observe the crash or the red "Unknown control" box in the UI.

Code sample

Code

import flet as ft

def main(page: ft.Page):
# This should work according to docs, but throws TypeError in v0.84.0
try:
file_picker = ft.FilePicker(on_result=lambda e: print(e))
page.overlay.append(file_picker)
except TypeError as e:
print(f"FilePicker Init Error: {e}")

# This also throws TypeError in v0.84.0
try:
    text_field = ft.TextField(placeholder="Test placeholder")
    page.add(text_field)
except TypeError as e:
    print(f"TextField Init Error: {e}")

# UI Feedback
page.add(
    ft.Text("If you see 'Unknown control' red boxes above, the bug is reproduced."),
    ft.ElevatedButton("Pick Files", on_click=lambda _: file_picker.pick_files())
)

ft.app(target=main)

To reproduce

import flet as ft

def main(page: ft.Page):
# This should work according to docs, but throws TypeError in v0.84.0
try:
file_picker = ft.FilePicker(on_result=lambda e: print(e))
page.overlay.append(file_picker)
except TypeError as e:
print(f"FilePicker Init Error: {e}")

# This also throws TypeError in v0.84.0
try:
    text_field = ft.TextField(placeholder="Test placeholder")
    page.add(text_field)
except TypeError as e:
    print(f"TextField Init Error: {e}")

# UI Feedback
page.add(
    ft.Text("If you see 'Unknown control' red boxes above, the bug is reproduced."),
    ft.ElevatedButton("Pick Files", on_click=lambda _: file_picker.pick_files())
)

ft.app(target=main)

Expected behavior

No response

Screenshots / Videos

Captures

[Upload media here]

Operating System

macOS

Operating system details

Tahoe 26

Flet version

0.84

Regression

No, it isn't

Suggestions

No response

Logs

Logs

[Paste your logs here]

Additional details

No response

[ndonkoHenri]

Hi @AlessioForconi, thanks for the report — but these aren't bugs, rather outdated API usage. The Flet API changed significantly in recent versions:

1. FilePicker is now a Service, not an overlay control. It no longer has an on_result event. Instead, its methods are async and return results directly. Don't add it to page.overlay — that's why you see the "Unknown control" red box. See the working examples here: https://flet.dev/docs/services/filepicker#examples

2. TextField uses hint_text, not placeholder:

ft.TextField(label="Name", hint_text="Jane Doe")

(If you're looking for the iOS-style control, CupertinoTextField uses placeholder_text)

Closing this ticket for now. Let know if you have additional concerns.