alhilali_device_preview

pub package

Preview your Flutter app inside realistic device frames, switch devices/orientation/system settings, and export clean marketing screenshots through the companion screenshot plugin.

alhilali_device_preview is a maintained fork of the original MIT-licensed device_preview package. This fork focuses on compatibility with recent Flutter releases and support for transparent framed PNG exports.

Features

  • Preview your app on phones, tablets, desktops, and custom devices.
  • Switch orientation, locale, theme, text scale, accessibility flags, and virtual keyboard state.
  • Keep app state while changing preview settings.
  • Use realistic device frames from alhilali_device_frame.
  • Extend the tool panel with plugins.
  • Export transparent framed screenshots with alhilali_device_preview_screenshot.

Install

Add the package to your app:

dependencies:
  alhilali_device_preview: ^1.3.5

Then import it:

import 'package:alhilali_device_preview/alhilali_device_preview.dart';

Basic Usage

Wrap your app with DevicePreview in main.dart.

import 'package:alhilali_device_preview/alhilali_device_preview.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    DevicePreview(
      enabled: !kReleaseMode,
      builder: (context) => const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      locale: DevicePreview.locale(context),
      builder: DevicePreview.appBuilder,
      theme: ThemeData.light(),
      darkTheme: ThemeData.dark(),
      home: const HomePage(),
    );
  }
}

DevicePreview.appBuilder applies the simulated media query, theme, text scale, safe areas, and other preview values to your app.

Add Screenshot Export

Install the screenshot plugin:

dependencies:
  alhilali_device_preview: ^1.3.5
  alhilali_device_preview_screenshot: ^1.1.0

Then add DevicePreviewScreenshot to the tool list:

import 'package:alhilali_device_preview/alhilali_device_preview.dart';
import 'package:alhilali_device_preview_screenshot/alhilali_device_preview_screenshot.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    DevicePreview(
      enabled: !kReleaseMode,
      tools: const [
        ...DevicePreview.defaultTools,
        DevicePreviewScreenshot(pixelRatio: 4),
      ],
      builder: (context) => const MyApp(),
    ),
  );
}

In the Device Preview toolbar, open the screenshot section and click Export transparent PNG.

How To Make The Screenshot Button Appear

The screenshot export button does not appear by installing the package only. You must add the screenshot plugin to the tools list of DevicePreview.

  1. Install both packages:
dependencies:
  alhilali_device_preview: ^1.3.5
  alhilali_device_preview_screenshot: ^1.1.0
  1. Import both packages:
import 'package:alhilali_device_preview/alhilali_device_preview.dart';
import 'package:alhilali_device_preview_screenshot/alhilali_device_preview_screenshot.dart';
  1. Add DevicePreviewScreenshot after the default tools:
DevicePreview(
  enabled: !kReleaseMode,
  tools: const [
    ...DevicePreview.defaultTools,
    DevicePreviewScreenshot(pixelRatio: 4),
  ],
  builder: (context) => const MyApp(),
)
  1. Run the app in debug mode:
flutter run
  1. Open the Device Preview side panel and look for the screenshot/export section. The action is named Export transparent PNG.

If the button does not appear, check these points:

  • The app is running with DevicePreview(enabled: true).
  • DevicePreviewScreenshot is included in tools.
  • You imported alhilali_device_preview_screenshot.
  • You are not running a release build with enabled: !kReleaseMode.

The exported image includes:

  • the device frame
  • screen content
  • bezels
  • notches and dynamic islands
  • visible frame decorations

The exported image excludes:

  • editor background
  • Device Preview workspace background
  • app canvas outside the device frame
  • toolbars and overlays outside the previewed device

Where Screenshots Are Saved

By default, DevicePreviewScreenshot() saves the PNG automatically in a user-accessible location:

  • Android: Pictures/DevicePreviewExports
  • Windows, macOS, and Linux: device_preview_exports in the current working directory
  • Other dart:io platforms: device_preview_exports inside the app documents directory

No custom MediaStore setup is needed for the default export flow.

If you want a specific directory or custom upload behavior, pass your own screenshot processor:

import 'dart:io';

import 'package:alhilali_device_preview_screenshot/alhilali_device_preview_screenshot.dart';

final outputDirectory = Directory('screenshots')..createSync(recursive: true);

DevicePreviewScreenshot(
  pixelRatio: 4,
  onScreenshot: screenshotAsFiles(outputDirectory),
)

For Android gallery/media storage, see the plugin README:

alhilali_device_preview_screenshot

Android Permissions

The default Android export uses media_store_plus and saves to Pictures/DevicePreviewExports. On modern Android versions, this does not usually require your app to ask for storage permission just to save the generated PNG.

If your app targets older Android devices, especially Android 9/API 28 or below, add the legacy storage permissions in android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission
        android:name="android.permission.READ_EXTERNAL_STORAGE"
        android:maxSdkVersion="32" />
    <uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"
        android:maxSdkVersion="29" />

    <application
        android:requestLegacyExternalStorage="true"
        ...>
    </application>
</manifest>

For most new apps, the basic setup is still just:

DevicePreviewScreenshot(pixelRatio: 4)

A complete implementation is available in the example project:

examples/transparent_png_export_example

Use Custom Devices

You can add your own device definitions:

DevicePreview(
  devices: [
    ...Devices.ios.all,
    DeviceInfo.genericPhone(
      platform: TargetPlatform.android,
      name: 'Marketing Phone',
      id: 'marketing-phone',
      screenSize: const Size(430, 932),
      pixelRatio: 3,
      safeAreas: const EdgeInsets.only(top: 44, bottom: 34),
      rotatedSafeAreas: const EdgeInsets.symmetric(horizontal: 44),
    ),
  ],
  builder: (context) => const MyApp(),
)

Use Device Preview only in debug/profile builds:

DevicePreview(
  enabled: !kReleaseMode,
  builder: (context) => const MyApp(),
)

You can also disable it with a compile-time flag:

DevicePreview(
  enabled: const bool.fromEnvironment('DEVICE_PREVIEW', defaultValue: true),
  builder: (context) => const MyApp(),
)

Run with:

flutter run --dart-define=DEVICE_PREVIEW=false

Example

This repository includes a complete example for transparent PNG export:

examples/transparent_png_export_example

It demonstrates:

  • DevicePreview
  • the screenshot plugin
  • high-resolution export
  • automatic saving to a user-accessible export folder

Packages

Limitations

Device Preview approximates how your app appears on another device. It does not replace testing on real devices, especially for platform APIs, performance, camera, sensors, permissions, native views, and store-specific screenshot requirements.

License

MIT. Original copyright notices are preserved.

Libraries

alhilali_device_preview