`<MediaQuery>`

Overview

The <MediaQuery> component exposes Flutter's MediaQuery data to child widgets via dependencies, making screen size, orientation, padding, and accessibility settings available in your XML markup. It's essential for building responsive layouts that adapt to different screen sizes and device capabilities.

All data is exposed through a configurable variable name (default: mediaQuery) that can be referenced in child widget expressions.

Attributes

Name	Type	Description	Required	Default
`varName`	String	The variable name used to access media query data in dependencies	No	`"mediaQuery"`
`smallMaxWidth`	int	Maximum width (in logical pixels) for "small" layout classification	No	`640`
`mediumMaxWidth`	int	Maximum width (in logical pixels) for "medium" layout classification. Larger screens are "large"	No	`1024`
`dependenciesScope`	String	How to scope dependencies: `"copy"` (default), `"inherit"`, or `"new"`	No	`"copy"`
`key`	Key	Widget key for controlling widget identity	No	`null`
`for`	String	The name of the parent's attribute that will be assigned this component	No	`null`
`visible`	bool	Controls widget visibility	No	`true`

Available Properties

When using the default varName of "mediaQuery", the following properties are available:

Screen Size

Property	Type	Description
`mediaQuery.size.width`	double	Screen width in logical pixels
`mediaQuery.size.height`	double	Screen height in logical pixels
`mediaQuery.size.layout`	String	`"small"`, `"medium"`, or `"large"` based on width breakpoints

View Insets

View insets represent the portions of the screen covered by system UI (like the keyboard):

Property	Type	Description
`mediaQuery.viewInsets.left`	double	Left inset in logical pixels
`mediaQuery.viewInsets.top`	double	Top inset in logical pixels
`mediaQuery.viewInsets.right`	double	Right inset in logical pixels
`mediaQuery.viewInsets.bottom`	double	Bottom inset (e.g., keyboard height)
`mediaQuery.viewInsets.horizontal`	double	Sum of left + right insets
`mediaQuery.viewInsets.vertical`	double	Sum of top + bottom insets

View Padding

View padding represents safe area insets (notches, status bars, navigation bars):

Property	Type	Description
`mediaQuery.viewPadding.left`	double	Left padding in logical pixels
`mediaQuery.viewPadding.top`	double	Top padding (status bar)
`mediaQuery.viewPadding.right`	double	Right padding in logical pixels
`mediaQuery.viewPadding.bottom`	double	Bottom padding (navigation bar)
`mediaQuery.viewPadding.horizontal`	double	Sum of left + right padding
`mediaQuery.viewPadding.vertical`	double	Sum of top + bottom padding

Platform Settings

Property	Type	Description
`mediaQuery.orientation`	String	`"portrait"` or `"landscape"`
`mediaQuery.platformBrightness`	Brightness	`Brightness.light` or `Brightness.dark`
`mediaQuery.boldText`	bool	Whether bold text accessibility setting is enabled
`mediaQuery.highContrast`	bool	Whether high contrast accessibility setting is enabled
`mediaQuery.disableAnimations`	bool	Whether reduce motion accessibility setting is enabled

Examples

Basic Usage

<MediaQuery>
    <Column>
        <Text data="Width: ${toString(mediaQuery.size.width)}px"/>
        <Text data="Height: ${toString(mediaQuery.size.height)}px"/>
        <Text data="Layout: ${mediaQuery.size.layout}"/>
    </Column>
</MediaQuery>

Responsive Layout

<MediaQuery>
    <!-- Mobile layout -->
    <Column visible="${mediaQuery.size.layout == 'small'}">
        <fragment name="mobile_nav"/>
        <fragment name="content"/>
    </Column>

    <!-- Tablet / Desktop layout -->
    <Row visible="${mediaQuery.size.layout != 'small'}">
        <fragment name="sidebar"/>
        <fragment name="content"/>
    </Row>
</MediaQuery>

Custom Breakpoints

<MediaQuery smallMaxWidth="480" mediumMaxWidth="1280">
    <Text visible="${mediaQuery.size.layout == 'small'}" data="Mobile"/>
    <Text visible="${mediaQuery.size.layout == 'medium'}" data="Tablet"/>
    <Text visible="${mediaQuery.size.layout == 'large'}" data="Desktop"/>
</MediaQuery>

Handling Keyboard Visibility

<MediaQuery>
    <Column>
        <Expanded>
            <fragment name="chat_messages"/>
        </Expanded>
        <fragment name="chat_input"/>
        <SizedBox height="${mediaQuery.viewInsets.bottom}"/>
    </Column>
</MediaQuery>

Orientation-Based Layout

<MediaQuery>
    <Column visible="${mediaQuery.orientation == 'portrait'}">
        <fragment name="portrait_layout"/>
    </Column>
    <Row visible="${mediaQuery.orientation == 'landscape'}">
        <fragment name="landscape_layout"/>
    </Row>
</MediaQuery>

Custom Variable Name

<MediaQuery varName="mq">
    <Column>
        <Text data="Width: ${toString(mq.size.width)}"/>
        <Text data="Layout: ${mq.size.layout}"/>
    </Column>
</MediaQuery>

Safe Area Padding

<MediaQuery>
    <Column>
        <SizedBox height="${mediaQuery.viewPadding.top}"/>
        <Expanded>
            <fragment name="content"/>
        </Expanded>
        <SizedBox height="${mediaQuery.viewPadding.bottom}"/>
    </Column>
</MediaQuery>

Breakpoint Guidelines

The default breakpoints follow common responsive design patterns:

Small (≤640px): Mobile phones in portrait
Medium (641px–1024px): Large phones, small tablets, tablets in portrait
Large (>1024px): Tablets in landscape, desktops, large screens

Customize breakpoints using smallMaxWidth and mediumMaxWidth to match your design system.

<MediaQuery>