Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 42 ยท Controls and Binding

Common Controls

A tour of the everyday .NET MAUI controls - Label, Button, Entry, Editor, Image, Switch, Slider, Stepper, ProgressBar, ActivityIndicator, Border and ImageButton - with properties and events.

MAUI ships with a large set of ready-made controls. This lesson covers the ones almost every app uses: text (Label), input (Entry, Editor, Switch, Slider, Stepper), buttons, images, progress indicators and the Border container. Lists, pickers and validation have their own lessons.

MAUI controls cannot run on this site, so the XAML is read-only. The runnable blocks are labelled C# stand-ins that model the rules of some controls (value clamping, text events), because those rules matter in your code.

Label

Label displays text. Useful properties: Text, TextColor, FontSize, FontAttributes (Bold, Italic), FontFamily, HorizontalTextAlignment, LineBreakMode (WordWrap, TailTruncation...), MaxLines, TextDecorations (Underline, Strikethrough) and TextTransform (Uppercase, Lowercase).

XML
<Label Text="Total: $42.00" FontSize="22" FontAttributes="Bold"
       TextColor="{StaticResource Primary}" MaxLines="1" LineBreakMode="TailTruncation" />

For mixed formatting in one label use FormattedText with Span elements; for a tappable link, give a Span a GestureRecognizers tap, or use the HyperlinkLabel pattern with a TapGestureRecognizer:

XML
<Label>
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Read the " />
            <Span Text="terms" TextColor="Blue" TextDecorations="Underline">
                <Span.GestureRecognizers>
                    <TapGestureRecognizer Command="{Binding OpenTermsCommand}" />
                </Span.GestureRecognizers>
            </Span>
        </FormattedString>
    </Label.FormattedText>
</Label>

Button, ImageButton

Button has Text, Clicked, Command and CommandParameter, plus appearance: BackgroundColor, TextColor, CornerRadius, BorderColor, BorderWidth, ImageSource (an icon next to the text) and ContentLayout (icon position). ImageButton shows only an image. Pressed and Released events exist as well.

XML
<Button Text="Sign in" Command="{Binding SignInCommand}" CornerRadius="8" />
<ImageButton Source="delete" WidthRequest="40" HeightRequest="40" Clicked="OnDeleteClicked" />

A button is disabled when its command's CanExecute returns false, or when you set IsEnabled="False". You will use commands in the MVVM lesson.

Entry and Editor

Entry is single-line text input; Editor is multi-line. Shared properties include Text, Placeholder, MaxLength, IsReadOnly, Keyboard, ReturnType and the events TextChanged and Completed. Entry adds IsPassword, ClearButtonVisibility and IsTextPredictionEnabled.

XML
<Entry Placeholder="Email" Keyboard="Email" ReturnType="Next" />
<Entry Placeholder="Password" IsPassword="True" />
<Editor Placeholder="Notes" AutoSize="TextChanges" HeightRequest="120" />

Keyboard selects the on-screen keyboard: Default, Email, Numeric, Telephone, Url, Chat, Text. TextChanged gives e.OldTextValue and e.NewTextValue (strings, may be null); Completed fires when the user presses the return key.

C#
private void OnEmailChanged(object? sender, TextChangedEventArgs e)
{
    var entry = (Entry)sender!;
    entry.TextColor = (e.NewTextValue ?? "").Contains('@') ? Colors.Black : Colors.Red;
}

Switch, Slider, Stepper

Control Value Change event Notes
Switch IsToggled (bool) Toggled OnColor, ThumbColor
Slider Value (double) ValueChanged Minimum, Maximum; defaults 0 to 1
Stepper Value (double) ValueChanged Minimum, Maximum, Increment
CheckBox IsChecked CheckedChanged Color
RadioButton IsChecked CheckedChanged Group with GroupName, content can be any view

Slider and Stepper clamp the value into [Minimum, Maximum]. The stand-in below shows that rule, including a pitfall: set Minimum and Maximum in the right order, because MAUI throws if you set a minimum larger than the current maximum.

C# Stand-in: Slider-style clamping and events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The same pattern (store the value, ignore no-ops, raise a changed event) is what every bindable property does, which you will see in the data binding lesson.

Image

Image shows pictures from several sources through its Source property:

XML
<Image Source="dotnet_bot" Aspect="AspectFit" HeightRequest="120" />       <!-- project resource -->
<Image Source="https://example.com/photo.jpg" />                           <!-- web (cached) -->
<Image Source="{Binding AvatarStream}" />                                  <!-- ImageSource in a view model -->

Aspect is AspectFit (whole image, may leave margins), AspectFill (fills, may crop) or Fill (stretches). Set IsOpaque, IsAnimationPlaying (animated GIFs) and SemanticProperties.Description for accessibility. Set a HeightRequest for web images so layout does not jump when they load.

ProgressBar, ActivityIndicator, Border, BoxView

  • ProgressBar shows a value from 0 to 1 (Progress, with ProgressTo(0.8, 500, Easing.Linear) to animate).
  • ActivityIndicator is a spinner: IsRunning="True" (also set IsVisible when finished).
  • Border draws a border, rounded corners, a shadow and holds one child (it replaces the old Frame): Stroke, StrokeThickness, StrokeShape="RoundRectangle 12".
  • BoxView paints a coloured rectangle, handy as a divider.
XML
<Border Stroke="LightGray" StrokeThickness="1" Padding="12" StrokeShape="RoundRectangle 12">
    <VerticalStackLayout>
        <Label Text="Downloading..." />
        <ProgressBar Progress="0.4" />
    </VerticalStackLayout>
</Border>

Text input behaviour you must code yourself

The second stand-in handles a typical Entry.TextChanged job: keep only digits for a phone field. Note the guard against re-entry: assigning Text inside TextChanged raises the event again, which can loop forever if you are not careful.

C# Stand-in: filtering text in a TextChanged handler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Accessibility basics

Add SemanticProperties.Description (and Hint) to images and icon buttons so screen readers can describe them, use sufficient colour contrast, and never use colour alone to convey meaning. AutomationId gives UI tests a stable name for a control.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which Keyboard value shows a numeric keypad?

    Keyboard.Numeric is the numbers keyboard; Telephone shows a dial pad.
  2. 2. What happens when Slider.Value is set above Maximum?

    Slider and Stepper clamp values into the Minimum-Maximum range.
  3. 3. Which control replaces the old Frame for borders and rounded corners?

    Border has Stroke, StrokeThickness and StrokeShape, and is the recommended replacement for Frame.
  4. 4. Which Image.Aspect value fills the area and may crop the picture?

    AspectFill scales the picture until it covers the area, which can crop edges.
  5. 5. Why can setting Entry.Text inside TextChanged be dangerous?

    Each assignment that changes the text raises the event again; only assign when the value differs.

Summary

  • Label, Button, Entry, Editor, Switch, Slider, Stepper, Image, ProgressBar, Border cover most screens.
  • Each control exposes a main value property and a change event.
  • Slider and Stepper clamp to their range; Entry.TextChanged handlers must avoid endless loops.
  • Add semantic descriptions for accessibility.

Next: Input Controls and Pickers