FormItem Class

A list element that serves as a single item in a composite UI structure such as a data entry form, profile page, menu, action sheet, or settings panel.

Namespace: DevExpress.Maui.Editors

Assembly: DevExpress.Maui.Editors.dll

NuGet Package: DevExpress.Maui.Editors

Declaration

[ContentProperty("Content")]
public class FormItem :
    FormItemBase,
    FormItemBase.ContentTemplateConnector.IContentElement,
    FormItemBase.InlineContentTemplateConnector.IInlineContentElement

Remarks

A FormItem can display header text, description, arrow, icon, and additional custom content. Users can tap a FormItem to invoke an action.

The following diagram depicts form items and their elements:

DevExpress Form Item for MAUI - Anatomy

For a list of all available form items, refer to the following help topic: Form Items.

Add a Form Item to a Page

Before you proceed, read the following topic:

Get Started with DevExpress Controls for .NET Multi-platform App UI (.NET MAUI)

Once you completed the general setup steps outlined in the article above, declare the DevExpress.Maui.Editors namespace in your markup:

XAML

<ContentPage
    xmlns:dxe="clr-namespace:DevExpress.Maui.Editors;assembly=DevExpress.Maui.Editors">
    <!--...-->
</ContentPage>

You can use any layout class to arrange form items on the form. The following example adds FormItem objects to a VerticalStackLayout. To combine form items into groups, you can use the FormGroupItem:

XAML

<ScrollView>
    <VerticalStackLayout>
        <dxe:FormGroupItem>
            <dxe:FormItem .../>
            <dxe:FormItem .../>
            <!--...-->
        </dxe:FormGroupItem>
    </VerticalStackLayout>
</ScrollView>

Refer to our repo on GitHub to review the complete source code:

View Example

Customize Text Settings

The Text specifies the FormItem‘s primary text (header). Use the following properties to configure a form item’s text and its appearance:

Text: Specifies the content of a form item’s primary text.
TextColor: Specifies the form item text’s color.
TextFontAttributes: Defines font attributes for the form item’s text. You can use the following options: Bold, Italic, or None.
TextFontFamily: Specifies the text’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.
TextFontSize: Defines the text’s font size.
TextLineBreakMode: Specifies the line break mode for a font item’s text.
TextMargin: Allows you to set the gaps between the text and other form item elements.
TextMaxLineCount: Defines the maximum number of text lines.

Example: Configure the Text for a Form Item

The markup below adds a text header to a form item and specifies text settings:

XAML

<dxe:FormItem Text="Brightness level"
              TextColor="Gray"
              TextFontAttributes="Bold"
              TextFontFamily="OpenSansRegular"
              TextFontSize="18"
              TextLineBreakMode="CharacterWrap"
              TextMargin="4"
              TextMaxLineCount="2"/>

Customize Detail Text Settings

The Detail specifies the FormItem’s secondary text (description). Use the following properties to configure a form item’s detail text and its appearance:

Detail: Specifies the content of a form item’s secondary text.
DetailColor: Specifies the form item detail’s color.
DetailFontAttributes: Defines font attributes for the form item’s detail. You can use the following options: Bold, Italic, or None.
DetailFontFamily: Specifies the detail’s font name. You can only use fonts previously registered in the app. For more information, refer to: Register Fonts.
DetailFontSize: Defines the detail’s font size.
DetailLineBreakMode: Specifies the line breaking mode for a font item’s detail.
DetailMargin: Allows you to set the gaps between the detail and other form item elements.
DetailMaxLineCount: Defines the maximum number of detail lines.

Example: Configure the Detail Text for a Form Item

The markup below adds secondary text for a form item and configures text options :

XAML

<dxe:FormItem Detail="The reading mode adjusts colors and
              textures in order to reduce eye strain."
              DetailColor="LightGray"
              DetailFontAttributes="Italic"
              DetailFontFamily="OpenSansRegular"
              DetailFontSize="14"
              DetailLineBreakMode="TailTruncation"
              DetailMargin="4"
              DetailMaxLineCount="2"/>

Respond to User Taps

The API members below allow you to respond to user taps:

AllowTap: Specifies whether taps on the form item are allowed.
TapCommand: Defines the command that is executed when a user taps the form item.
TapCommandParameter: Specifies the Tap command parameter.
Tap: Occurs when a user taps the form item.

The following example executes a command when a user taps a form item:

XAML

<dxe:FormItem ...
              AllowTap="True"
              TapCommand="{Binding OnTapCommand}">

using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;

namespace FormItemsTestApp;

public partial class MainPage : ContentPage {
    public MainPage() {
        InitializeComponent();
        this.BindingContext = new MainPageViewModel();
    }
}

public class MainPageViewModel {
    //...
    public ICommand OnTapCommand => new Command(OnFormItemTap);
    private void OnFormItemTap() {
        // Perform actions when the form item is tapped.
        // ...
    }

}

Example: Edit the Detail in a Separate Page

You can also open an edit form in a separate page once a user taps the form item:

DevExpress FormItem for MAUI - Edit detail

View Example

XAML

<dxe:FormItem AllowTap="True" Detail="{Binding Bio, Converter={helpers:BioDetailsConverter}, Mode=OneWay}" DetailColor="Gray"
    TapCommand="{Binding EditBioCommand}" Text="{Binding Bio, Converter={helpers:BioTextConverter}, Mode=OneWay}" />

Customize the Image

The properties listed in this section allow you to configure the settings of a form item’s icon:

ImageSource

Specifies the image source. In XAML, use the name of an image in the Resources/Images folder to define the source. Ensure that the image’s Build Action is MauiImage.

For more information about images, refer to the following page: Add images to a .NET MAUI app project.

ImageColor

Defines the tint color of the form item’s image.

ImageHeight

Specifies the height of the form item’s image.

ImageWidth

Specifies the width of the form item’s image.

ImageMargin

Allows you to set the gaps between the image and other form item elements.

ImageVerticalOptions

Specifies how the image is positioned vertically. You can use the following options: Fill, Center, Start, and End.

ImageTemplate

Defines a template that configures image appearance.

Example: Configure the Image Icon for a Form Item

The following example configures image settings:

DevExpress FormItem for MAUI - Image customization

XAML

<dxe:FormItem Text="Brightness level"
              TextMargin="4,4,4,16"
              InlineContent="80%"
              ShowArrow="True"
              ImageSource="brightness"
              ImageColor="#F9C938"
              ImageHeight="36"
              ImageWidth="36"
              ImageMargin="4"
              ImageVerticalOptions="Start">
</dxe:FormItem>

Example: Use a Template to Configure the Image

The following example shows how to create a DataTemplate to customize the image’s content:

DevExpress FormItem for MAUI - Image template customization

XAML

<ContentPage ...
             xmlns:dxco="clr-namespace:DevExpress.Maui.Controls;assembly=DevExpress.Maui.Controls"
             ...>
        <ScrollView>
            <VerticalStackLayout>
                <dxe:FormItem Text="Brightness level"
                              TextMargin="4,4,4,16"
                              InlineContent="80%"
                              ShowArrow="True">
                    <dxe:FormItem.ImageTemplate>
                        <DataTemplate>
                            <Border StrokeThickness="2" Stroke="LightGray"
                                    WidthRequest="50" HeightRequest="50"
                                    VerticalOptions="Start">
                                <dxco:DXImage Source="brightness"
                                              TintColor="#F9C938"
                                              WidthRequest="30"
                                              HeightRequest="30"/>
                            </Border>
                        </DataTemplate>
                    </dxe:FormItem.ImageTemplate>
                </dxe:FormItem>
            </VerticalStackLayout>
        </ScrollView>
</ContentPage>

Customize the Inline Content

The Form Item displays the Inline Content to the right of the arrow. The inline content can contain any image and/or text information. Use the following properties to set up the Inline Content:

InlineContent: Specifies the content of a form item’s inline content.
InlineContentTemplate: Defines the template that specifies the appearance of the inline content.

Example: Configure a Template for the Inline Content

The example below how to create a template that configures the text color for inline content:

XAML

<ContentPage.Resources>
    <DataTemplate x:Key="inlineContentTemplate">
        <Label Text="{Binding}" TextColor="#999999"/>
    </DataTemplate>
</ContentPage.Resources>
<ScrollView>
    <VerticalStackLayout>
        <dxe:FormItem ...
                        InlineContent="60 Hz"
                        InlineContentTemplate="{StaticResource inlineContentTemplate}"/>
    </VerticalStackLayout>
</ScrollView>

Customize Arrow

An Arrow indicates that a user can tap the form item to perform an action. Use the following settings to display the arrow and customize it:

ShowArrow: Specifies whether to show the form item’s arrow.
ArrowColor: Sets the arrow’s fill color.
ArrowTemplate: Specifies a template that configures the arrow’s appearance.
ArrowMargin: Allows you to set the gaps between the arrow and other form item elements.
ArrowVerticalOptions: Specifies how the arrow is positioned vertically. You can use the following options: Fill, Center, Start, and End.

Example: Specify the Default Arrow’s Settings

The following markup customizes the default arrow’s settings for a Form Item:

XAML

<dxe:FormItem ShowArrow="True"
              ArrowColor="Gray"
              ArrowMargin="10"
              ArrowVerticalOptions="Center"/>

Example: Configure the Arrow Template

The following markup shows how to replace the default arrow icon with a custom icon:

XAML

<dxe:FormItem ...
              ShowArrow="True">
    <dxe:FormItem.ArrowTemplate>
        <DataTemplate>
            <dxco:DXImage Source="rightarrow"
                          WidthRequest="30"
                          HeightRequest="30"
                          TintColor="Coral" />
        </DataTemplate>
    </dxe:FormItem.ArrowTemplate>
</dxe:FormItem>

Customize Separator

The Separator is a line that separates form items. The settings below allow you to show a form item’s separator and define its appearance:

ShowSeparator: Specifies whether the separator is visible.
SeparatorColor: Defines the separator’s fill color.
SeparatorThickness: Specifies the separator’s thickness.

XAML

<dxe:FormItem ShowSeparator="True"
              SeparatorColor="LightGray"
              SeparatorThickness="1">

Show Additional Content

You can show any content in a Form Item. Use the following properties to specify the content and its appearance:

Content: Specifies the form item’s content.
ContentTemplate: Sets the template that configures the content’s appearance.

The following example shows how to create a form item with custom content:

DevExpress Form Item for MAUI

XAML

<dxe:FormItem ShowSeparator="True" Padding="10,20">
    <dxe:FormItem.ContentTemplate>
        <DataTemplate>
            <Frame BorderColor="Gray" BackgroundColor="#20606060" CornerRadius="10">
                <VerticalStackLayout>
                    <Label Text="Need other settings?" />
                    <Label Text="Font settings" TextColor="CornflowerBlue">
                        <Label.GestureRecognizers>
                            <TapGestureRecognizer Tapped="TapGestureRecognizer_Tapped" />
                        </Label.GestureRecognizers>
                    </Label>
                    <Label Text="Status bar settings" TextColor="CornflowerBlue">
                        <Label.GestureRecognizers>
                            <TapGestureRecognizer Tapped="TapGestureRecognizer_Tapped"/>
                        </Label.GestureRecognizers>
                    </Label>
                </VerticalStackLayout>
            </Frame>
        </DataTemplate>
    </dxe:FormItem.ContentTemplate>
</dxe:FormItem>

The following featured scenario shows how you can use the FormItem class:

Use Form Items to Build a Settings Page