flet-notifications

Cross-platform local notifications for Flet apps.

A 1:1 wrapping of the official flutter_local_notifications Flutter plugin, in the same architecture as flet-ads. One uv add flet-notifications covers Android, iOS, macOS, Windows, Linux and Web — no Python dependencies beyond flet (verified on Flet 0.85.0 through 1.0.x in CI).

Test it without an account

Every release builds the example app for every platform. Sideload any of them and every button is live:

Plain flet run launches the prebuilt client without the extension's Dart half — notifications need a built app (an artifact above, or flet build <platform>).

Platform Support

Usage

uv add flet-notifications

import flet as ft
from flet_notifications import LocalNotifications

def main(page: ft.Page):
    notifications = LocalNotifications()

    async def on_tap(e):
        print("tapped:", e.payload)

    notifications.on_tap = on_tap

    if await notifications.request_permissions():
        await notifications.show(id=1, title="Hello", body="Hello!")

ft.run(main)

Controls

Event handlers

notifications.on_tap = on_tap          # typed: NotificationEvent
notifications.on_action = on_action    # typed: e.action_id, e.input, e.data
notifications.on_dismissed = handler   # typed

Typed handlers must use ft.EventHandler[NotificationEvent], not ft.ControlEventHandler[NotificationEvent] — ControlEventHandler[X] double-wraps X in Event[...], so e.payload raises AttributeError. NotificationEvent carries id, action_id, payload, input, data and response_type.

Taps that arrive while the app wasn't running are replayed on the next start (Android background taps, iOS/macOS cold-start launches).

Configuration

Scheduling on Android needs permissions in the app's pyproject.toml:

[tool.flet.android.permission]
RECEIVE_BOOT_COMPLETED = true   # restore alarms after reboot
SCHEDULE_EXACT_ALARM = true     # exact schedule modes

The scheduled-notification receivers are <application> children, which [tool.flet.android.*] cannot declare — the flet-notifications-patch console script injects them (plus the core-library-desugaring Gradle flags the plugin needs), idempotently:

uv run flet build apk --yes --project myapp --org com.example -v
uv run flet-notifications-patch --project-root build/flutter
cd build/flutter/android && ./gradlew assembleRelease -Psplit-per-abi=true

Configuration reference

Types: NotificationAction/NotificationActionInput (buttons, inline reply) · BigTextStyle/BigPictureStyle/InboxStyle/MessagingStyle (+ Person, Message, AndroidIcon) · NotificationChannel (importance, sound, vibration, badge, DND, lights) · NotificationOptions with AndroidOptions/DarwinOptions/LinuxOptions/WindowsOptions/WebOptions (the full per-platform detail surface) · enums RepeatInterval, DateTimeComponents, AndroidScheduleMode, Importance, GroupAlertBehavior, InterruptionLevel.

Calls: show · schedule · periodically_show · cancel/cancel_all/cancel_pending · request_permissions · are_notifications_enabled · can_schedule_exact_notifications/request_exact_alarm_permission · request_full_screen_intent_permission · has/request_notification_policy_access · open_app_notification_settings · get_pending_notifications/get_active_notifications/get_notification_app_launch_details · create/delete/get_notification_channels (+ groups) · start/stop_foreground_service.

Errors: NotificationError with a stable code — unsupported_platform, init_failed, show_failed, schedule_failed, invalid_action, invalid_schedule, invalid_style, invalid_channel, invalid_option, invalid_service_id, channel_failed, foreground_service_failed, query_failed, permission_failed, unknown_method.

Limitations

• Linux/Web have no OS scheduler; Windows schedules one-shot only.
• Android channel sound/vibration are immutable after creation; aggressive OEM skins may drop alarms after force-stop; Samsung caps ~500 alarms.
• Interruptions beyond passive on Apple need Xcode capabilities.
• Not wrapped (upstream niche): HTML-format style flags, MediaStyle, action semanticAction/invisible/contextual, CarPlay, message data MIME/URI, Linux custom hints.
• iOS IPAs need Apple signing and are built owner-side; CI builds every other platform.

Example

examples/flet_notifications_example — every API on one screen with a timestamped event log, built for Windows, macOS, Linux, Android and Web on every release.

License

MIT