launchUrl function

Future<void> launchUrl(Uri url, { bool prefersDeepLink = false, CustomTabsOptions? customTabsOptions, SafariViewControllerOptions? safariVCOptions, })

Launches a web URL using a Custom Tab or browser, with various customization options.

The launchUrl function provides a way to open web content within your app using a customizable in-app browser experience on Android and iOS platforms.

Supported Platforms

• Android: Uses Custom Tabs to display web content within your app. Customize the appearance and behavior using the customTabsOptions parameter.
• iOS: Uses SFSafariViewController to present web content. Customize using the safariVCOptions parameter.
• Web: Customization options are not available; the URL will be opened in a new browser tab.

Examples

Launch a URL with customization:

final theme = ...;
try {
  await launchUrl(
    Uri.parse('https://flutter.dev'),
    customTabsOptions: CustomTabsOptions(
      colorSchemes: CustomTabsColorSchemes.defaults(
        toolbarColor: theme.colorScheme.surface,
      ),
      urlBarHidingEnabled: true,
      showTitle: true,
      closeButton: CustomTabsCloseButton(
        icon: CustomTabsCloseButtonIcons.back,
      ),
    ),
    safariVCOptions: SafariViewControllerOptions(
      preferredBarTintColor: theme.colorScheme.surface,
      preferredControlTintColor: theme.colorScheme.onSurface,
      barCollapsingEnabled: true,
      dismissButtonStyle: SafariViewControllerDismissButtonStyle.close,
    ),
  );
} catch (e) {
  // If the URL launch fails, an exception will be thrown. (For example, if no browser app is installed on the Android device.)
}

Launch a URL in the external browser:

try {
  await launchUrl(Uri.parse('https://flutter.dev'));
} catch (e) {
  // An exception is thrown if browser app is not installed on Android device.
}

Notes

• The URL must have an http or https scheme; otherwise, a PlatformException is thrown.
• Use closeCustomTabs to programmatically close the Custom Tab if needed.
• Make sure to call the warmupCustomTabs function before launching the URL to improve performance.

Implementation

Future<void> launchUrl(
  Uri url, {
  bool prefersDeepLink = false,
  CustomTabsOptions? customTabsOptions,
  SafariViewControllerOptions? safariVCOptions,
}) {
  return CustomTabsPlatform.instance.launch(
    _requireWebUrl(url),
    prefersDeepLink: prefersDeepLink,
    customTabsOptions: customTabsOptions,
    safariVCOptions: safariVCOptions,
  );
}