Buttons

A button gives the user a way to trigger an immediate action.

Important APIs: Button class, RepeatButton class, Click event

Example of buttons

Is this the right control?

A button lets the user initiate an immediate action, such as submitting a form.

Don't use a button when the action is to navigate to another page; use a link instead. See Hyperlinks for more info.

Exception: For wizard navigation, use buttons labeled "Back" and "Next". For other types of backwards navigation or navigation to an upper level, use a back button.

Example

This example uses two buttons, Allow and Block, in a dialog requesting location access.

Example of buttons, used in a dialog

Create a button

This example shows a button that responds to a click.

Create the button in XAML.

<Button Content="Subscribe" Click="SubscribeButton_Click"/>

Or create the button in code.

Button subscribeButton = new Button();
subscribeButton.Content = "Subscribe";
subscribeButton.Click += SubscribeButton_Click;

// Add the button to a parent container in the visual tree.
stackPanel1.Children.Add(subscribeButton);

Handle the Click event.

private async void SubscribeButton_Click(object sender, RoutedEventArgs e)
{
    // Call app specific code to subscribe to the service. For example:
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it"
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Button interaction

When you tap a Button with a finger or stylus, or press a left mouse button while the pointer is over it, the button raises the Click event. If a button has keyboard focus, pressing the Enter key or the Spacebar key also raises the Click event.

You generally can't handle low-level PointerPressed events on a Button because it has the Click behavior instead. For more info, see Events and routed events overview.

You can change how a button raises the Click event by changing the ClickMode property. The default ClickMode value is Release. If ClickMode is Hover, the Click event can't be raised with the keyboard or touch.

Button content

Button is a ContentControl. Its XAML content property is Content, which enables a syntax like this for XAML: <Button>A button's content</Button>. You can set any object as the button's content. If the content is a UIElement, it is rendered in the button. If the content is another type of object, its string representation is shown in the button.

Here, a StackPanel that contains an image of an orange and text is set as the content of a button.

<Button Click="Button_Click"
        Background="LightGray"
        Height="100" Width="80">
    <StackPanel>
        <Image Source="Assets/Photo.png" Height="62"/>
        <TextBlock Text="Photos" Foreground="Black"
                   HorizontalAlignment="Center"/>
    </StackPanel>
</Button>

The button looks like this.

A button with image and text content

Create a repeat button

A RepeatButton is a button that raises Click events repeatedly from the time it's pressed until it's released. Set the Delay property to specify the time that the RepeatButton waits after it is pressed before it starts repeating the click action. Set the Interval property to specify the time between repetitions of the click action. Times for both properties are specified in milliseconds.

The following example shows two RepeatButton controls whose respective Click events are used to increase and decrease the value shown in a text block.

<StackPanel>
    <RepeatButton Width="100" Delay="500" Interval="100" Click="Increase_Click">Increase</RepeatButton>
    <RepeatButton Width="100" Delay="500" Interval="100" Click="Decrease_Click">Decrease</RepeatButton>
    <TextBlock x:Name="clickTextBlock" Text="Number of Clicks:" />
</StackPanel>
private static int _clicks = 0;
private void Increase_Click(object sender, RoutedEventArgs e)
{
    _clicks += 1;
    clickTextBlock.Text = "Number of Clicks: " + _clicks;
}

private void Decrease_Click(object sender, RoutedEventArgs e)
{
    if(_clicks > 0)
    {
        _clicks -= 1;
        clickTextBlock.Text = "Number of Clicks: " + _clicks;
    }
}

Recommendations

  • Make sure the purpose and state of a button are clear to the user.
  • Use a concise, specific, self-explanatory text that clearly describes the action that the button performs. Usually button text content is a single word, a verb.
  • When there are multiple buttons for the same decision (such as in a confirmation dialog), present the commit buttons in this order:

    • OK/[Do it]/Yes
    • [Don't do it]/No
    • Cancel

    (where [Do it] and [Don't do it] are specific responses to the main instruction.)

  • If the button's text content is dynamic, for example, it is localized, consider how the button will resize and what will happen to controls around it.

  • For command buttons with text content, use a minimum button width.
  • Avoid narrow, short, or tall command buttons with text content.
  • Use the default font unless your brand guidelines tell you to use something different.
  • For an action that needs to be available across multiple pages within your app, instead of duplicating a button on multiple pages, consider using a bottom app bar.
  • Expose only one or two buttons to the user at a time, for example, Accept and Cancel. If you need to expose more actions to the user, consider using checkboxes or radio buttons from which the user can select actions, with a single command button to trigger those actions.
  • Use the default command button to indicate the most common or recommended action.
  • Consider customizing your buttons. A button's shape is rectangular by default, but you can customize the visuals that make up the button's appearance. A button's content is usually text—for example, Accept or Cancel—but you could replace the text with an icon, or use an icon plus text.
  • Make sure that as the user interacts with a button, the button changes state and appearance to provide feedback to the user. Normal, pressed, and disabled are examples of button states.
  • Trigger the button's action when the user taps or presses the button. Usually the action is triggered when the user releases the button, but you also can set a button's action to trigger when a finger first presses it.
  • Don't swap the default submit, reset, and button styles.
  • Don't put too much content inside a button. Make the content concise and easy to understand.

If your layout requires only one button, it should be either left- or right-aligned based on its container context.

  • Dialogs with only one button should right-align the button. If your dialog contains only one button, ensure that the button performs the safe, nondestructive action. If you use ContentDialog and specify a single button, it will automatically right-align.

A button within a dialog

  • If your button appears within a container UI (for example, within a toast notification, a flyout, or a list view item), you should right-align the button within the container.

A button within a container

  • In pages that contain a single button (for example, an "Apply" button at the bottom of a settings page), you should left-align the button. This ensures that the button aligns with the rest of the page content.

A button on a page

Back buttons

The back button is a system-provided UI element that enables backward navigation through either the back stack or navigation history of the user. You don't have to create your own back button, but you might have to do some work to enable a good backwards navigation experience. For more info, see History and backwards navigation

Get the sample code