he Button is one of the most important controls in WinUI 3 because it lets the user trigger an immediate action, such as confirming a choice, starting a task, or submitting data. Microsoft’s guidance describes the standard Button as the control to use when the user needs to initiate an immediate action, while navigation should usually use HyperlinkButton instead. (Microsoft Learn)

Understanding the Button Control in WinUI 3 (Step-by-Step Guide)

Introduction

The Button is one of the most important controls in WinUI 3 because it lets the user trigger an immediate action, such as confirming a choice, starting a task, or submitting data. Microsoft’s guidance describes the standard Button as the control to use when the user needs to initiate an immediate action, while navigation should usually use HyperlinkButton instead. (Microsoft Learn)

In this first atomic app, we will build the simplest useful example possible: a window with one button and one text label. When the user clicks the button, the text changes. This keeps the lesson focused on the core idea of the control: reacting to the Click event. That fits your project rule of studying one concept at a time, keeping the example isolated, runnable, explicit, and simple.

What We Are Building

The final app has only two visible elements:

• a Button
• a TextBlock

At startup, the text says that the button has not been clicked yet. After the user clicks the button, the text changes to confirm the action. This is a small app, but it teaches the essential behavior of a WinUI 3 button in the clearest possible way.

Step 0 — Create the Project

Create a new Blank App, Packaged (WinUI 3 in Desktop) project in Visual Studio. Microsoft’s current Windows App SDK tutorial uses that template for a basic WinUI 3 app. (Microsoft Learn)

For this learning project, keep the structure simple: one solution, one main project, and one page per concept. That is exactly aligned with your project rules.

Step 1 — Create the UI in XAML

Open MainWindow.xaml and replace the default content with this:

<Window
    x:Class="App01_ButtonClickBasic.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Title="App01 - Button Click Basic">
    <StackPanel
        Spacing="16"
        HorizontalAlignment="Center"
        VerticalAlignment="Center">
        <TextBlock
            x:Name="StatusText"
            Text="The button has not been clicked yet."
            FontSize="18"
            TextAlignment="Center" />
        <Button
            x:Name="ActionButton"
            Content="Click Me"
            Click="ActionButton_Click"
            HorizontalAlignment="Center" />
    </StackPanel>
</Window>

Why this XAML is intentionally simple

StackPanel places the elements vertically, which is enough for this example and avoids introducing layout complexity too early. That matches the atomic-learning approach in your project.

TextBlock is used only to show feedback to the user.

Button is the main control of the lesson. In WinUI 3, Button is a content control, so its visible label is usually set through the Content property. The Click event is the standard event used to react to user activation. (Microsoft Learn)

Step 2 — Add the C# Behavior

Open MainWindow.xaml.cs and use this code:

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
namespace App01_ButtonClickBasic
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }
        private void ActionButton_Click(object sender, RoutedEventArgs e)
        {
            StatusText.Text = "You clicked the button.";
        }
    }
}

Why this code is enough

The constructor calls InitializeComponent() so the XAML UI is loaded.

The ActionButton_Click method is the event handler connected in XAML through Click="ActionButton_Click".

When the button is clicked, we update the Text property of the TextBlock.

That is all we need. No MVVM, no commands, no services, no abstractions. For App 01, the goal is only to understand the button’s most direct interaction model. This follows your instruction to avoid overengineering and use C# only when behavior is necessary.

Step 3 — Run and Observe

When the app starts, the window shows the initial message and the button.

When the user clicks the button:

1. the Click event fires
2. the event handler runs
3. the text changes on screen

That is the full interaction cycle for this first app.

Key Concepts Behind the Button Control

1. Content

The Content property defines what appears inside the button. In basic examples, this is usually text such as "Click Me", but technically a button can host more than plain text because it is a content control. (Microsoft Learn)

2. Click

The Click event is the most important event for a basic button. It is the standard way to respond when the user activates the control. Microsoft’s control guidance explicitly identifies Click as the key event for a standard button. (Microsoft Learn)

3. ClickMode

A button can change when the Click event is raised through the ClickMode property. The default value is Release, which means the event is raised when the press is completed in the normal way. Microsoft also notes that Hover exists, but if ClickMode is set to Hover, the button cannot raise Click from the keyboard. For App 01, keep the default. (Microsoft Learn)

4. Visual States

Buttons in WinUI use visual states such as Normal, PointerOver, Pressed, and Disabled. Even if we do not customize them yet, it is important to know they exist because they explain why the button changes appearance during interaction. Microsoft’s visual state example for a button specifically references these common states. (Microsoft Learn)

Common Mistakes

Adding too much logic too early

For a first lesson, do not introduce commands, data binding, or MVVM. Those are useful later, but they hide the simple relationship between the button and the Click event.

Mixing multiple controls in the same lesson

Do not turn App 01 into a form, dialog, or navigation sample. This app should only teach one thing well: basic button click behavior. That matches your project rule of one isolated concept per module.

Using a Button for navigation

Microsoft recommends using HyperlinkButton when the intent is navigation instead of an immediate action. A normal Button is better when the user is executing something now. (Microsoft Learn)

Styling too soon

Do not start with custom templates, animations, or theme resources here. First understand behavior, then later study appearance and visual states in dedicated apps.

When and Why to Use a Button

Use a Button when the user needs to trigger an immediate action, for example:

• save data
• submit a form
• start a calculation
• confirm an operation
• open a dialog

Use HyperlinkButton when the main purpose is to navigate. Use RepeatButton when the same action should happen continuously while pressed. Use ToggleButton when the control represents an on/off state instead of a one-time action. Microsoft’s control guidance makes these distinctions clearly. (Microsoft Learn)

Why This Example Matters

This app is small, but it teaches a pattern you will use constantly in desktop UI development:

• define a control in XAML
• connect an event
• update the interface in response

That makes it a perfect App 01 for your atomic WinUI 3 learning roadmap.

Summary

In this first WinUI 3 app, we created a minimal interface with a Button and a TextBlock. The button uses the Content property for its label and the Click event for interaction. When the user clicks the button, a short C# event handler updates the text on screen.

This is exactly the right starting point because it is simple, explicit, and fully focused on one core concept.

Final Summary Table