Skip to main content

FletApp

Renders another Flet app in the current app, similar to HTML IFrame, but for Flet.

Inherits: LayoutControl

Properties

  • app_error_message - Template message to display when the app fails to load.
  • args - Optional dictionary of arguments to pass to the Flet app.
  • assets_dir - Base location for assets referenced by the embedded app.
  • boot_screen_name - Name of the boot screen to show while the embedded app starts up.
  • boot_screen_options - Options for the boot screen, passed through to the boot screen widget.
  • force_pyodide - Whether to force the use of Pyodide.
  • media_padding - Overrides the safe-area insets the embedded app sees.
  • platform_brightness - Overrides the system light/dark appearance the embedded app sees.
  • reconnect_interval_ms - Delay, in milliseconds, between reconnection attempts.
  • reconnect_timeout_ms - Total time to try reconnecting.
  • route - The embedded app's current route.
  • title - The embedded app's page.title.
  • url - Flet app URL, e.g.
  • window_state - The simulated window the embedded app should believe it lives in.

Events

  • on_connect - Fires when the client allocates an in-process dart_bridge channel for this embedded app (url="dartbridge://").
  • on_error - Called when a connection or any unhandled error occurs.
  • on_python_output - Fires once per stdout/stderr write inside the embedded Pyodide app.
  • on_route_change - Called when the embedded app navigates itself.
  • on_title_change - Called when the embedded app sets page.title.
  • on_window_event - Called when the embedded app asks its window to do something - a method call like page.window.close(), or a property write like page.window.maximized = True.

Methods

  • wait_idle - Waits until the embedded app has rendered its UI and gone quiet.

Properties​

app_error_messageclass-attributeinstance-attribute​

app_error_message: str | None = None

Template message to display when the app fails to load. Use {message} placeholder to include the error message and {details} to include error details.

argsclass-attributeinstance-attribute​

args: dict[str, Any] | None = None

Optional dictionary of arguments to pass to the Flet app.

assets_dirclass-attributeinstance-attribute​

assets_dir: str | None = None

Base location for assets referenced by the embedded app. On web this is a URL prefix joined with relative src values (e.g. on Image/Lottie/Markdown); on desktop it is a filesystem path.

boot_screen_nameclass-attributeinstance-attribute​

boot_screen_name: str | None = None

Name of the boot screen to show while the embedded app starts up.

When None, the built-in "flet" boot screen is used. Custom boot screens are provided by extensions; see the boot screen docs.

boot_screen_optionsclass-attributeinstance-attribute​

boot_screen_options: dict[str, Any] | None = None

Options for the boot screen, passed through to the boot screen widget.

For the built-in "flet" screen these include spinner_size, startup_message, bgcolor_light/bgcolor_dark, etc. See the boot screen docs.

force_pyodideclass-attributeinstance-attribute​

force_pyodide: bool = False

Whether to force the use of Pyodide.

media_paddingclass-attributeinstance-attribute​

media_padding: PaddingValue | None = None

Overrides the safe-area insets the embedded app sees.

The embedded app normally inherits the host window's MediaQuery, so on a desktop window its insets are zero regardless of what the app is being previewed as. Setting this makes the embedded app lay out as though it had those insets: page.media.padding reports them, and SafeArea avoids them.

Intended for previewing a phone layout inside a desktop window - a device frame in a designer, say - where the chrome drawn around the app is not something the platform knows about.

platform_brightnessclass-attributeinstance-attribute​

platform_brightness: Brightness | None = None

Overrides the system light/dark appearance the embedded app sees.

By default the embedded app follows the host's platform brightness. Set this to preview it as though its device were in light or dark mode: an app whose theme_mode is SYSTEM switches to its dark or light theme, page.platform_brightness reports the value, and on_platform_brightness_change fires when it changes. An app that forces LIGHT or DARK keeps it, as on a real device.

None follows the host.

reconnect_interval_msclass-attributeinstance-attribute​

reconnect_interval_ms: int | None = None

Delay, in milliseconds, between reconnection attempts.

reconnect_timeout_msclass-attributeinstance-attribute​

reconnect_timeout_ms: int | None = None

Total time to try reconnecting.

routeclass-attributeinstance-attribute​

route: str | None = None

The embedded app's current route.

Two-way: setting it navigates the embedded app, and when the embedded app navigates itself this property is updated to match and on_route_change fires. Leave it None to let the embedded app own its own routing.

Note

The embedded app routes locally - it never touches the browser address bar or the platform's deep links, both of which belong to the host app.

titleclass-attributeinstance-attribute​

title: str | None = None

The embedded app's page.title.

Written by the client whenever the embedded app sets its title, together with on_title_change. A guest's title belongs to whatever window its host draws around it - it does not touch the real OS window, because the window service is suppressed for embedded apps.

urlclass-attributeinstance-attribute​

url: str | None = None

Flet app URL, e.g. http://localhost:8550 or flet.sock.

window_stateclass-attributeinstance-attribute​

window_state: dict[str, Any] | None = None

The simulated window the embedded app should believe it lives in.

Keys are Window property names - width, height, top, left, maximized, minimized, full_screen, focused. What you set here is what the embedded app reads back from page.window, and changing it raises the matching page.window.on_event inside the app (resize, maximize, focus, ...) exactly as a real window would.

An embedded app never drives the real OS window, so without this its page.window is inert.

Events​

on_connectclass-attributeinstance-attribute​

on_connect: ControlEventHandler[FletApp] | None = None

Fires when the client allocates an in-process dart_bridge channel for this embedded app (url="dartbridge://"). The event data is the Dart native port the host must serve with a FletDartBridgeServer so the embedded app connects over it instead of a socket.

Advanced / embedder use — hosts that run another Flet program in-process (e.g. a gallery or preview) start their server on this port in the handler.

on_errorclass-attributeinstance-attribute​

on_error: ControlEventHandler[FletApp] | None = None

Called when a connection or any unhandled error occurs.

on_python_outputclass-attributeinstance-attribute​

on_python_output: (
    EventHandler[FletAppOutputEvent] | None
) = None

Fires once per stdout/stderr write inside the embedded Pyodide app. Pyodide line-buffers by default, so each event is typically one print(...) call. Only fires for embedded FletApps with force_pyodide=True; root-level Pyodide pages have nowhere to bubble the event.

on_route_changeclass-attributeinstance-attribute​

on_route_change: ControlEventHandler[FletApp] | None = None

Called when the embedded app navigates itself. The event data is the new route, which is also written back to route.

Does not fire for navigation the host itself caused by setting route.

on_title_changeclass-attributeinstance-attribute​

on_title_change: ControlEventHandler[FletApp] | None = None

Called when the embedded app sets page.title. The event data is the new title, which is also written back to title.

on_window_eventclass-attributeinstance-attribute​

on_window_event: EventHandler[FletAppWindowEvent] | None = (
    None
)

Called when the embedded app asks its window to do something - a method call like page.window.close(), or a property write like page.window.maximized = True.

A request, not a command: nothing happens unless the host acts on it, which is how a host that does not simulate, say, minimizing simply ignores it.

Methods​

wait_idleasync​

wait_idle(
    idle_ms: int = 300, timeout_ms: int = 30000
) -> dict[str, Any]

Waits until the embedded app has rendered its UI and gone quiet.

Useful for a host that needs to know when the embedded app is ready, e.g. before taking a screenshot of it or reading its output after a restart.

Parameters:

  • idle_ms (int, default: 300) - How long, in milliseconds, the embedded app must send no UI updates after its first one to count as idle.
  • timeout_ms (int, default: 30000) - Give up after this many milliseconds.

Returns:

  • dict[str, Any] - A dict with status and error. status is "idle" once the
  • dict[str, Any] - app sent at least one UI update, then none for idle_ms, and
  • dict[str, Any] - that update is on screen; "error" if the app failed to start
  • dict[str, Any] - or crashed (error holds the message; on_error fires as
  • dict[str, Any] - well); "timeout" if it didn't settle within timeout_ms, for
  • dict[str, Any] - example an app that updates continuously. A new call supersedes
  • dict[str, Any] - a pending one, which returns "timeout".