MediaQuery — What It Is, How It Works, and Responsive Layouts

What is MediaQuery

MediaQuery is a widget and class in Flutter that provides data about the application's media environment. MediaQuery wraps the entire application at the root MaterialApp or CupertinoApp widget, and any child widget can access this data via MediaQuery.of(context).

When Flutter launches an application, it creates an instance of MediaQueryData containing all the metrics of the current device. This data updates automatically on changes: device rotation, window resize (on desktop), keyboard appearance, or changes to system accessibility settings. MediaQuery rebuilds the widget subtree on any data change, providing reactive interface adaptation.

MediaQueryData includes: size (screen size), devicePixelRatio (pixel density), textScaleFactor (font scale from system settings), viewInsets (area covered by keyboard), viewPadding (system insets), orientation, and platformBrightness (light or dark theme).

In summary: MediaQuery is the central source of device information in Flutter. Accessing MediaQuery.of(context) is the first step in building any responsive interface.

Key Properties of MediaQueryData

MediaQueryData contains dozens of properties, but the most commonly used ones are those that affect layout construction. Let's look at the key ones.

Size — Screen Size

MediaQuery.of(context).size returns a Size object with the screen width and height in device-independent pixels (dip). These values do not account for system insets. For responsive layout calculations, size is the primary metric: it determines breakpoints for mobile, tablet, and desktop layouts.

ViewPadding — System Insets

ViewPadding refers to the insets that the system reserves for the status bar, notch (screen cutout), system navigation panel, and home indicator (on iOS). Without accounting for these insets, content may appear beneath system elements. MediaQuery.of(context).padding returns an EdgeInsets that should be applied as padding to the root container of the page.

ViewInsets — Keyboard Area

ViewInsets refers to the screen area covered by the software keyboard. For input fields, it is critical to monitor viewInsets.bottom to lift content above the keyboard. Flutter handles this automatically in scaffold, but for custom layouts you need to use MediaQuery.of(context).viewInsets directly.

Orientation — Device Orientation

Orientation — portrait or landscape orientation. It is determined by comparing width and height: if width is less than height — portrait, otherwise — landscape. In production code, orientation is used to switch between vertical and horizontal element arrangement.

In summary: four key properties — size, viewPadding, viewInsets, and orientation — cover 90% of responsive design tasks. The remaining properties (textScaleFactor, platformBrightness, devicePixelRatio) are used for specific scenarios.

Using MediaQuery for Responsive Layouts

MediaQuery is the foundation of responsive design in Flutter. It determines breakpoints, switches layout based on screen size, and adjusts insets for different devices.

Typical scenario: a mobile app needs to display a product list. On a phone (width < 600dp) — one column. On a tablet (width 600–900dp) — two columns. On desktop (width > 900dp) — three columns. MediaQuery.of(context).size.width allows dynamically selecting the number of columns without a separate screen for each form factor.

Second scenario: accounting for system gesture insets on modern devices. On iPhones with Dynamic Island or Android with gesture navigation, system insets consume part of the screen. MediaQuery.of(context).padding returns correct values for each device type, and Scaffold automatically applies them via body. For custom widgets, you need to explicitly pass padding from MediaQuery.

Third scenario: adapting to system accessibility settings. MediaQuery.of(context).textScaleFactor shows how much the user has increased the font size in settings. At textScaleFactor > 1.3, the layout may break — long texts overflow card boundaries. Responsive layouts should account for this and, if necessary, switch to a simpler layout.

In summary: MediaQuery is not just a source of metrics, but a tool for building truly responsive interfaces. Use it for breakpoints, safe area, and accessibility considerations.

Code Examples with MediaQuery

Example 1 demonstrates getting the screen size and applying breakpoints to select the number of columns.

int getColumnCount(BuildContext context) {
  final width = MediaQuery.of(context).size.width;
  if (width > 900) return 3;
  if (width > 600) return 2;
  return 1;
}

The example above shows a function for selecting the number of columns based on screen width. Breakpoints 600 and 900 correspond to the generally accepted Material Design standards for phones, tablets, and desktop.

Example 2 — using MediaQuery with viewPadding for correct content placement considering system insets.

Widget build(BuildContext context) {
  final padding = MediaQuery.of(context).padding;

  return Padding(
    padding: EdgeInsets.only(
      top: padding.top,
      left: padding.left,
      right: padding.right,
    ),
    child: const MyContent(),
  );
}

In this example, padding wraps the content in Padding using system insets. top accounts for the status bar and notch, left/right for safe areas. bottom is not included because Scaffold typically handles bottom navigation itself.

Example 3 — determining orientation and switching element arrangement.

Widget build(BuildContext context) {
  final isPortrait = MediaQuery.of(context).orientation == Orientation.portrait;

  return isPortrait
      ? const Column(
          children: [HeaderBanner(), ContentList()],
        )
      : const Row(
          children: [HeaderBanner(), ContentList()],
        );
}

In portrait mode, elements are arranged vertically (Column); in landscape mode, horizontally (Row). This approach makes the best use of space when the device is rotated.

In summary: MediaQuery is the main tool for building responsive layouts. Always consider system insets, breakpoints, and orientation when developing Flutter interfaces.

Common Mistakes When Working with MediaQuery

Mistake 1: calling MediaQuery.of(context) outside a context where MediaQuery is set. If a widget is above MediaQuery in the tree, the call causes a runtime error. Solution: always call MediaQuery.of(context) inside widgets wrapped by MaterialApp or CupertinoApp, where MediaQuery is set as the root widget.

Mistake 2: forgetting about safe area. Developers use MediaQuery.size to position elements without accounting for system insets. On devices with a notch or gesture navigation, content ends up under the status bar. Solution: subtract MediaQuery.of(context).padding from positioning coordinates.

Mistake 3: rigid size binding. Using MediaQuery.of(context).size.width to set exact element sizes (width: size.width * 0.3) only works on devices of the same form factor. On desktop or tablet, the layout looks unnatural. Solution: use breakpoints in combination with Expanded and Flexible for a flexible layout, not hard percentages.

Mistake 4: ignoring textScaleFactor. When the user increases the system font, the interface may break — texts overflow container boundaries. Solution: check MediaQuery.of(context).textScaleFactor and at values above 1.3 switch to a simpler scrollable layout.

In summary: MediaQuery is a powerful but subtle tool. Consider system insets, orientation, and accessibility settings to ensure the interface looks correct on all devices.