API reference

Import package:restart_app/restart_app.dart to use these types.

Restart.restartApp

Requests a restart or web reload and returns a Future<RestartResult>.

static Future<RestartResult> restartApp({
  RestartMode mode = RestartMode.platformDefault,
  String? webOrigin,
  String? notificationTitle,
  String? notificationBody,
  bool forceKill = false,
})

The default behavior depends on the platform. Pass mode to request another supported behavior. See configuration for parameter defaults and examples. If your app has unsaved data, finish and await those writes before calling. The request can stop the Dart isolate or unload the browser document before later code finishes.

Web destinations

On web, only RestartMode.platformDefault is supported. webOrigin determines the destination:

Value	Behavior
`null` or `''`	Reload the Flutter app’s browser URL, preserving its path, query, and fragment.
Hash only, such as `#/home`	Set the fragment and reload. A changed fragment adds a browser history entry.
Full or relative URL for the same document	Replace the history entry and reload, even if the URL is identical or only its fragment differs.
Full or relative URL for a different document	Navigate with `window.location.replace`, replacing the history entry.

Relative URLs resolve against document.baseURI, including an HTML <base href> element. URLs match the same document when they are equal after removing their fragments. The default reload does not change the URL to your app’s initial route. An app embedded in an iframe reloads its own frame.

Restart.restartCapability

Returns a Future<RestartCapability> describing which restart behaviors the platform provides.

static Future<RestartCapability> restartCapability()

Use it to decide which restart options to show. These capabilities do not guarantee that a request will succeed: for example, an iOS engine restart also needs the app to be active and have a suitable window. Web supports the default reload even though its process, engine, and notification flags are all false. Missing plugin registration and platform-channel errors return unavailable capabilities. The reason field explains the failure when an explanation is available.

RestartMode

Value	Behavior
`platformDefault`	Use the platform’s default restart or reload.
`flutterEngine`	Recreate the Flutter engine in the existing process. Supported on configured iOS hosts.
`process`	Relaunch on Android, macOS, and Windows, or replace the running process image on Linux. Unsupported on iOS and web.
`notificationFallback`	Schedule an iOS local notification and close the app. The user must tap the notification to reopen it.

RestartResult

Field	Meaning
`success`	`true` when the platform accepts the request. It does not confirm that the replacement app or engine has finished starting.
`mode`	The resolved mode on success; the requested mode on failure.
`code`	An error identifier when the request fails, otherwise `null`.
`message`	An error description when available, otherwise `null`.

Native platforms may perform the restart after sending a successful result. A failure during that later work is written to native logs and cannot change the result already returned to Dart.

RestartCapability

Field	Meaning
`fullProcessRestart`	Whether the platform supports a process restart. Linux replaces the process image with `execv` and keeps its PID.
`flutterEngineRestart`	Whether engine restart is available in the existing native process.
`notificationFallback`	Whether the iOS notification fallback is available. This does not report notification permission.
`engineRestartConfigured`	Whether the host has configured engine restart.
`platformDefaultMode`	The mode selected for `RestartMode.platformDefault`.
`reason`	An optional explanation of an unavailable or limited capability.

Failures

Platform errors are returned as RestartResult values with success: false. Read code and message to decide how your app should respond.

Code	Meaning
`MISSING_PLUGIN`	The native plugin is not registered. Rebuild the app after adding the package.
`UNKNOWN_RESULT`	The native plugin returned an unrecognized response.
`UNSUPPORTED_RESTART_MODE`	The requested mode is not supported on this platform.
`IOS_ENGINE_RESTART_NOT_CONFIGURED`	The iOS host needs plugin registration for replacement engines.
`IOS_PROCESS_RESTART_UNSUPPORTED`	iOS cannot automatically relaunch the app in a new process. Use engine restart or offer the explicit notification fallback.
`RESTART_ALREADY_IN_PROGRESS`	Android or a desktop platform is already handling an earlier restart request.
`IOS_RESTART_ALREADY_IN_PROGRESS`	iOS is already handling an engine restart or notification fallback.

Send one restart request per user action. Disable repeated taps as soon as the action starts. If the request fails, show the failure and let the user try again after addressing its cause. Call from the main isolate. If you invoke the API before runApp, first call WidgetsFlutterBinding.ensureInitialized(). See background isolates for worker coordination.

Start

Guides

Reference

Restart.restartApp

Web destinations

Restart.restartCapability

RestartMode

RestartResult

RestartCapability

Failures

​Restart.restartApp

​Web destinations

​Restart.restartCapability

​RestartMode

​RestartResult

​RestartCapability

​Failures

Restart.restartApp

Web destinations

Restart.restartCapability

RestartMode

RestartResult

RestartCapability

Failures