alhilali_device_preview 1.3.4

Preview Flutter apps on multiple devices with transparent framed PNG screenshot export.

alhilali_device_preview

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.3

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.3
  alhilali_device_preview_screenshot: ^1.0.1

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.3
  alhilali_device_preview_screenshot: ^1.0.1

2. Import both packages:

import 'package:alhilali_device_preview/alhilali_device_preview.dart';
import 'package:alhilali_device_preview_screenshot/alhilali_device_preview_screenshot.dart';

3. Add DevicePreviewScreenshot after the default tools:

DevicePreview(
  enabled: !kReleaseMode,
  tools: const [
    ...DevicePreview.defaultTools,
    DevicePreviewScreenshot(pixelRatio: 4),
  ],
  builder: (context) => const MyApp(),
)

4. Run the app in debug mode:

flutter run

5. 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

Save Screenshots To Files

By default, the screenshot plugin prints base64 PNG data. To save images to a directory, pass a 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 For Public Screenshot Saving

If you want exported screenshots to appear in a user-accessible Android folder such as Pictures/DevicePreviewExports, use media_store_plus in your app and add the required permissions to android/app/src/main/AndroidManifest.xml.

Add dependencies:

dependencies:
  alhilali_device_preview: ^1.3.4
  alhilali_device_preview_screenshot: ^1.0.1
  media_store_plus: ^0.1.3
  path_provider: ^2.1.5

Add permissions:

<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>

Then pass a custom ScreenshotProcessor to DevicePreviewScreenshot that saves the PNG through MediaStore.saveFile. 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(),
)

Recommended Development Setup

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
• saving Android screenshots to a public Pictures folder using media_store_plus

Packages

• alhilali_device_frame: device frame rendering.
• alhilali_device_preview: preview UI and state management.
• alhilali_device_preview_screenshot: transparent PNG export plugin.

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.