display_metrics

Flutter plugin that provides display metrics such as real screen resolution, physical display size, ppi, diagonal. Also it contains BuildContext extension to transform inches & millimeters into Flutter logical pixels.

Features

  • Get real screen resolution, display size (inches) and PPI
  • Convert inches and millimeters into Flutter logical pixels

Getting started

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

  @override
  Widget build(BuildContext context) {
    // add DisplayMetricsWidget to Widget tree above MaterialApp to use DisplayMetrics.of(context) and BuildContext extension methods
    return DisplayMetricsWidget(
      child: MaterialApp(
        home: Scaffold(
          appBar: AppBar(
            title: const Text('Display metrics example app'),
            centerTitle: true,
          ),
          body: const BodyWidget(),
        ),
      ),
    );
  }
}

Example app  Ruler

Usage

DisplayMetricsData

To access DisplayMetricsData you can call

final metrics = DisplayMetrics.maybeOf(context);
// or
final metrics = DisplayMetrics.of(context);
// Device's primary screen physical size in inches
metrics.physicalSize => Size

// Device's primary screen resolution in real pixels
metrics.resolution => Size

// Device's primary screen diagonal in inches
metrics.diagonal => double

// Device's primary screen pixels per inch (PPI)
metrics.ppi => double 

// The number of logical pixels on the device's primary screen
// that corresponds to one inch
metrics.inchesToLogicalPixelRatio => double

// MediaQuery`s devicePixelRatio
metrics.devicePixelRatio => double

// List of all available displays metrics
metrics.displays => List<ExtendedPhysicalDisplayData>

// Display metrics data of primary display
metrics.primaryDisplay => ExtendedPhysicalDisplayData

You can await for DisplayMetrics.ensureInitialized(context) to ensure that DisplayMetricsData is available.

Convert units

To convert inches and millimeters into Flutter logical pixels and vice versa you can call one of BuildContext extension methods:

// Converts inches to Flutter logical pixels
context.inchesToPixels(double inches);

// Converts millimeters to Flutter logical pixels
context.mmToPixels(double mm);

// Converts Flutter logical pixels into inches
context.pixelsToInches(int pixels);

// Converts Flutter logical pixels into millimeters
context.pixelsToMm(int pixels);

DisplayMetricsWidget

// Add [DisplayMetricsWidget] to Widget tree above MaterialApp to use DisplayMetrics.of(context) and BuildContext extension methods
DisplayMetricsWidget(
  child: child,
);

Unknown displays

New devices may be released after the package version you use, so their physical size is unknown to the package. Use onUnknownDisplay to provide the diagonal (in inches) yourself without waiting for a package update. Physical size and PPI are calculated from the diagonal and the display resolution.

// diagonals (in inches) of devices released after your package version
const myDiagonals = {'iPhone20,1': 6.3};

DisplayMetricsWidget(
  onUnknownDisplay: (info) {
    if (info case IosUnknownDisplayInfo(:final modelIdentifier)) {
      return myDiagonals[modelIdentifier];
    }
    return null;
  },
  child: child,
);

Please note:

  • info fields depend on the platform. On iOS it is IosUnknownDisplayInfo with the device model identifier (e.g. iPhone20,1). Currently only iOS reports unknown displays.
  • info.resolution is the resolution of the display the app is currently shown on (on iOS 13+ the screen of the foreground app scene), so for an unknown foldable device you can pick the diagonal by it.
  • The callback is called for every unknown display on every display metrics update, so it should be cheap and free of side effects.
  • If the callback returns null (or is not provided) during initial load, no data is available: DisplayMetrics.maybeOf(context) returns null and DisplayMetrics.ensureInitialized(context) completes with an error that names the device.
  • If the callback returns null after the display has changed (for example a foldable device was unfolded), DisplayMetrics.of(context) keeps returning the previous display's data and an error is logged.
  • Exceptions thrown by the callback are reported with FlutterError.reportError (so they reach FlutterError.onError, e.g. your crash reporting) once per display, and the display is treated as unknown.

Supported Platforms

Platform Support Multi-Display
iOS ✅ ❌
Android ✅ ✅
please read
the foldable devices
Windows ✅ ❌
macOS ✅ ❌
Linux ✅ ❌
Web ✅
please read
the limitations
❌

Swift Package Manager

Starting with display_metrics 2.4.0, the iOS and macOS implementations support both Swift Package Manager (SPM) and CocoaPods. Apps with Flutter's SPM integration enabled can use the plugin through SPM, while apps that use CocoaPods continue to work without changes. See Flutter's SPM guide for instructions on enabling SPM in an app.

Web limitations

Due to browser limitations, it's not possible to accurately determine the physical screen dimensions or the actual DPI on the web platform. Browsers use a unit called a CSS pixel, which is not a physical pixel but a unit based on a reference pixel, defined as 1/96th of an inch. This system depends on the viewing angle of the device and varies across displays, making it impossible to obtain accurate physical measurements or DPI through web APIs. You can read more here.

Foldable devices

On Android, this package now supports foldable and multi-display devices. When used on a device like the Pixel Fold, the plugin can detect the current active display and report its correct size - whether folded or unfolded.

Additionally, the displays getter returns a list of all connected displays (including external displays, if present).

Please note:

  • The display list may contain multiple entries depending on the device and configuration.
  • Each display includes its resolution in pixels, DPI, and a flag indicating whether it's the primary display.
  • Testing has been performed using the Pixel Fold emulator.
  • This feature is currently only supported on Android. Other platforms will always return a single display representing the main screen.

Credits

iOS implementation uses Jens Schwarzer's UIScreenExtension

Libraries

display_metrics