Edit

Share via

Customize UI appearance based on the platform and device idiom

  • Article

Browse sample. Browse the sample

.NET Multi-platform App UI (.NET MAUI) apps can have their UI customized for specific platforms and devices. This enables your app to:

  • Make the most effective use of space. If you design an app to look good on a mobile device, the app will still be usable on a desktop device but there will most likely be some wasted space. You can customize your app to display more content when the screen is above a certain size. For example, a shopping app might display one item at a time on a mobile device, but might show multiple items on a desktop device. In addition, by placing more content on screen you can reduce the amount of navigation that users need to perform.
  • Take advantage of device capabilities. Certain devices are more likely to have certain capabilities. For example, mobile devices are more likely to have a location sensor and a camera, while desktop devices might not have either. Your app can detect which capabilities are available and enable controls that use them.
  • Optimize for input. You can rearrange your UI elements to optimize for specific input types. For example, if you place navigation elements at the bottom of the app, they'll be easier for mobile users to access. But desktop users often expect to see navigation elements towards the top of the app.

When you optimize your app's UI for specific platforms and device idioms, you're creating a responsive UI. The primary approaches to creating a responsive UI in .NET MAUI involve using the OnPlatform markup extension and the OnIdiom markup extension.

Note

There is a category of triggers, known as state triggers, that can be used to customize UI appearance in specific scenarios such as when the orientation of a device changes. For more information, see State trigger.

Customize UI appearance based on the platform

The OnPlatform markup extension enables you to customize UI appearance on a per-platform basis. It provides the same functionality as the OnPlatform<T> and On classes, but with a more concise representation.

The OnPlatform markup extension is supported by the OnPlatformExtension class, which defines the following properties:

  • Default, of type object, that you set to a default value to be applied to the properties that represent platforms.
  • Android, of type object, that you set to a value to be applied on Android.
  • iOS, of type object, that you set to a value to be applied on iOS.
  • MacCatalyst, of type object, that you set to a value to be applied on Mac Catalyst.
  • Tizen, of type object, that you set to a value to be applied on the Tizen platform.
  • WinUI, of type object, that you set to a value to be applied on WinUI.
  • Converter, of type IValueConverter, that can be set to an IValueConverter implementation.
  • ConverterParameter, of type object, that can be set to a value to pass to the IValueConverter implementation.

Note

The XAML parser allows the OnPlatformExtension class to be abbreviated as OnPlatform.

The Default property is the content property of OnPlatformExtension. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the Default= part of the expression if it's the first argument. If the Default property isn't set, it defaults to the BindableProperty.DefaultValue property value, provided that the markup extension is targeting a BindableProperty.

Important

The XAML parser expects that values of the correct type will be provided to properties consuming the OnPlatform markup extension. If type conversion is necessary, the OnPlatform markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the Converter property should be set to an IValueConverter implementation.

The OnPlatform Demo page shows how to use the OnPlatform markup extension:

<BoxView Color="{OnPlatform Yellow, iOS=Red, Android=Green}"
         WidthRequest="{OnPlatform 250, iOS=200, Android=300}"
         HeightRequest="{OnPlatform 250, iOS=200, Android=300}"
         HorizontalOptions="Center" />

In this example, all three OnPlatform expressions use the abbreviated version of the OnPlatformExtension class name. The three OnPlatform markup extensions set the xref:Microsoft.Maui.Graphics.Color, WidthRequest, and HeightRequest properties of the BoxView to different values on iOS and Android. The markup extensions also provide default values for these properties on the platforms that aren't specified, while eliminating the Default= part of the expression.

Customize UI appearance based on the device idiom

The OnIdiom markup extension enables you to customize UI appearance based on the idiom of the device the app is running on. It's supported by the OnIdiomExtension class, which defines the following properties:

  • Default, of type object, that you set to a default value to be applied to the properties that represent device idioms.
  • Phone, of type object, that you set to a value to be applied on phones.
  • Tablet, of type object, that you set to a value to be applied on tablets. This property isn't exclusive to Android and iOS platforms.
  • Desktop, of type object, that you set to a value to be applied on desktop platforms. Note that some laptops may be classified using the Tablet property.
  • TV, of type object, that you set to a value to be applied on TV platforms.
  • Watch, of type object, that you set to a value to be applied on Watch platforms.
  • Converter, of type IValueConverter, that can be set to an IValueConverter implementation.
  • ConverterParameter, of type object, that can be set to a value to pass to the IValueConverter implementation.

Note

The XAML parser allows the OnIdiomExtension class to be abbreviated as OnIdiom.

The Default property is the content property of OnIdiomExtension. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the Default= part of the expression if it's the first argument.

Important

The XAML parser expects that values of the correct type will be provided to properties consuming the OnIdiom markup extension. If type conversion is necessary, the OnIdiom markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the Converter property should be set to an IValueConverter implementation.

The following XAML example shows how to use the OnIdiom markup extension:

<BoxView Color="{OnIdiom Yellow, Phone=Red, Tablet=Green, Desktop=Blue}"
         WidthRequest="{OnIdiom 100, Phone=200, Tablet=300, Desktop=400}"
         HeightRequest="{OnIdiom 100, Phone=200, Tablet=300, Desktop=400}"
         HorizontalOptions="Center" />

In this example, all three OnIdiom expressions use the abbreviated version of the OnIdiomExtension class name. The three OnIdiom markup extensions set the Color, WidthRequest, and HeightRequest properties of the BoxView to different values on the phone, tablet, and desktop idioms. The markup extensions also provide default values for these properties on the idioms that aren't specified, while eliminating the Default= part of the expression.