Button Styles

Specifies a combination of button styles. If you create a button using the BUTTON class with the CreateWindow or CreateWindowEx function, you can specify any of the button styles listed below.

Example

Constants

Constant	Description
BS_3STATE	Creates a button that is the same as a check box, except that the box can be grayed as well as checked or cleared. Use the grayed state to show that the state of the check box is not determined.
BS_AUTO3STATE	Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, indeterminate, and cleared.
BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that the check state automatically toggles between checked and cleared each time the user selects the check box.
BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, the system automatically sets the button’s check state to checked and automatically sets the check state for all other buttons in the same group to cleared.
BS_BITMAP	Specifies that the button displays a bitmap. See the Remarks section for its interaction with BS_ICON.
BS_BOTTOM	Places text at the bottom of the button rectangle.
BS_CENTER	Centers text horizontally in the button rectangle.
BS_CHECKBOX	Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style).
BS_COMMANDLINK	Creates a command link button that behaves like a BS_PUSHBUTTON style button, but the command link button has a green arrow on the left pointing to the button text. A caption for the button text can be set by sending the BCM_SETNOTE message to the button.
BS_DEFCOMMANDLINK	Creates a command link button that behaves like a BS_PUSHBUTTON style button. If the button is in a dialog box, the user can select the command link button by pressing the ENTER key, even when the command link button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_DEFPUSHBUTTON	Creates a push button that behaves like a BS_PUSHBUTTON style button, but has a distinct appearance. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_DEFSPLITBUTTON	Creates a split button that behaves like a BS_PUSHBUTTON style button, but also has a distinctive appearance. If the split button is in a dialog box, the user can select the split button by pressing the ENTER key, even when the split button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_GROUPBOX	Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle’s upper left corner.
BS_ICON	Specifies that the button displays an icon. See the Remarks section for its interaction with BS_BITMAP.
BS_FLAT	Specifies that the button is two-dimensional; it does not use the default shading to create a 3-D image.
BS_LEFT	Left-justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.
BS_LEFTTEXT	Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the BS_RIGHTBUTTON style.
BS_MULTILINE	Wraps the button text to multiple lines if the text string is too long to fit on a single line in the button rectangle.
BS_NOTIFY	Enables a button to send BN_KILLFOCUS and BN_SETFOCUS notification codes to its parent window. Note that buttons send the BN_CLICKED notification code regardless of whether it has this style. To get BN_DBLCLK notification codes, the button must have the BS_RADIOBUTTON or BS_OWNERDRAW style.
BS_OWNERDRAW	Creates an owner-drawn button. The owner window receives a WM_DRAWITEM message when a visual aspect of the button has changed. Do not combine the BS_OWNERDRAW style with any other button styles.
BS_PUSHBUTTON	Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_PUSHLIKE	Makes a button (such as a check box, three-state check box, or radio button) look and act like a push button. The button looks raised when it isn’t pushed or checked, and sunken when it is pushed or checked.
BS_RADIOBUTTON	Creates a small circle with text. By default, the text is displayed to the right of the circle. To display the text to the left of the circle, combine this flag with the BS_LEFTTEXT style (or with the equivalent BS_RIGHTBUTTON style). Use radio buttons for groups of related, but mutually exclusive choices.
BS_RIGHT	Right-justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.
BS_RIGHTBUTTON	Positions a radio button’s circle or a check box’s square on the right side of the button rectangle. Same as the BS_LEFTTEXT style.
BS_SPLITBUTTON	Creates a split button. A split button has a drop down arrow.
BS_TEXT	Specifies that the button displays text.
BS_TOP	Places text at the top of the button rectangle.
BS_TYPEMASK	Do not use this style. A composite style bit that results from using the OR operator on BS_* style bits. It can be used to mask out valid BS_* bits from a given bitmask. Note that this is out of date and does not correctly include all valid styles. Thus, you should not use this style.
BS_USERBUTTON	Obsolete, but provided for compatibility with 16-bit versions of Windows. Applications should use BS_OWNERDRAW instead.
BS_VCENTER	Places text in the middle (vertically) of the button rectangle.

Remarks

For illustrations of the principal button styles such as BS_CHECKBOX and BS_GROUPBOX, see Button Types.

The appearance of text or an icon or both on a button control depends on the BS_ICON and BS_BITMAP styles, and whether the BM_SETIMAGE message is sent. The possible results are as follows.

Buttons

A button gives the user a way to trigger an immediate action. Some buttons are specialized for particular tasks, such as navigation, repeated actions, or presenting menus.

The Extensible Application Markup Language (XAML) framework provides a standard button control as well as several specialized button controls.

Control	Description
Button	A button that initiates an immediate action. Can be used with a Click event or Command binding.
RepeatButton	A button that raises a Click event continuously while pressed.
HyperlinkButton	A button that’s styled like a hyperlink and used for navigation. For more info about hyperlinks, see Hyperlinks.
DropDownButton	A button with a chevron to open an attached flyout.
SplitButton	A button with two sides. One side initiates an action, and the other side opens a menu.
ToggleSplitButton	A toggle button with two sides. One side toggles on/off, and the other side opens a menu.
ToggleButton	A button that can be on or off.

Get the Windows UI Library

DropDownButton, SplitButton, and ToggleSplitButton are included as part of the Windows UI Library, a NuGet package that contains new controls and UI features for Windows apps. For more info, including installation instructions, see Windows UI Library.

Is this the right control?

Use a Button control to let the user initiate an immediate action, such as submitting a form.

Don’t use a Button control when the action is to navigate to another page; instead, use a HyperlinkButton control. For more info about hyperlinks, see Hyperlinks.

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.

Use a RepeatButton control when the user might want to trigger an action repeatedly. For example, use a RepeatButton control to increment or decrement a value in a counter.

Use a DropDownButton control when the button has a flyout that contains more options. The default chevron provides a visual indication that the button includes a flyout.

Use a SplitButton control when you want the user to be able to initiate an immediate action or choose from additional options independently.

Use a ToggleButton control when you want the user to be able to immediately switch between two mutually exclusive states, and a button is the best fit for your UI needs. Unless your UI benefits from a button, it might be a better choice to use an AppBarToggleButton, CheckBox, RadioButton, or ToggleSwitch.

Examples

If you have XAML Controls Gallery installed, click here to open the app and see the Button in action.

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

Create a button

This example shows a button that responds to a click.

Create the button in XAML.

Or create the button in code.

Handle the Click event.

Button interaction

When you tap a Button control 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 also raises the Click event.

You generally can’t handle low-level PointerPressed events on a Button object 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 value of ClickMode is Release, but you also can set a button’s ClickMode value to Hover or Press. If ClickMode is Hover, the Click event can’t be raised by using the keyboard or touch.

Button content

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

A button’s content is usually text. When you design that text, use the following recommendations:

Use a concise, specific, self-explanatory text that clearly describes the action that the button performs. Usually button text is a single word that is a verb.

Use the default font, unless your brand guidelines tell you to use something different.

For shorter text, avoid narrow command buttons by using a minimum button width of 120px.

For longer text, avoid wide command buttons by limiting text to a maximum length of 26 characters.

If the button’s text content is dynamic (that is, it is localized), consider how the button will be resized and what will happen to controls around it.

XAML Controls Gallery

Need to fix: Buttons with overflowing text.
Option 1: Increase button width, stack buttons, and wrap if text length is greater than 26 characters.
Option 2: Increase button height, and wrap text.

You can also customize visuals that make up the button’s appearance. For example, you could replace the text with an icon, or use an icon in addition to text.

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

The button looks like this.

Create a repeat button

A RepeatButton control 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 control 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.

Create a drop down button

DropDownButton requires the Windows UI Library or Windows 10, version 1809 (SDK 17763) or later. To download the latest SDK, see Windows 10 SDK; to download an earlier SDK, see Windows SDK and emulator archive.

A DropDownButton is a button that shows a chevron as a visual indicator that it has an attached flyout that contains more options. It has the same behavior as a standard Button control with a flyout; only the appearance is different.

The drop down button inherits the Click event, but you typically don’t use it. Instead, you use the Flyout property to attach a flyout and invoke actions by using menu options in the flyout. The flyout opens automatically when the button is clicked. Be sure to specify the Placement property of your flyout to ensure the desired placement in relation to the button. The default placement algorithm might not produce the intended placement in all situations.

For more info about flyouts, see Menus and context menus.

Example — Drop down button

This example shows how to create a drop down button with a flyout that contains commands for paragraph alignment in a RichEditBox control. (For more info and code, see Rich edit box).

Create a split button

SplitButton requires the Windows UI Library or Windows 10, version 1809 (SDK 17763) or later. To download the latest SDK, see Windows 10 SDK; to download an earlier SDK, see Windows SDK and emulator archive.

A SplitButton control has two parts that can be invoked separately. One part behaves like a standard button and invokes an immediate action. The other part invokes a flyout that contains additional options that the user can choose from.

When invoked with touch, the split button behaves as a drop down button; both halves of the button invoke the flyout. With other methods of input, a user can invoke either half of the button separately.

The typical behavior for a split button is:

When the user clicks the button part, handle the Click event to invoke the option that’s currently selected in the drop down.

When the drop down is open, handle invocation of the items in the drop down to both change which option is selected, and then invoke it. It’s important to invoke the flyout item because the button Click event doesn’t occur when using touch.

There are many ways to put items in the drop down and handle their invocation. If you use a ListView or GridView, one way is to handle the SelectionChanged event. If you do this, set SingleSelectionFollowsFocus to false. This lets users navigate the options using a keyboard without invoking the item on each change.

Example — Split button

This example shows how to create a split button that is used to change the foreground color of selected text in a RichEditBox control. (For more info and code, see Rich edit box). Split button’s flyout uses BottomEdgeAlignedLeft as the default value for its Placement property. You can’t override this value.

Create a toggle split button

ToggleSplitButton requires the Windows UI Library or Windows 10, version 1809 (SDK 17763) or later. To download the latest SDK, see Windows 10 SDK; to download an earlier SDK, see Windows SDK and emulator archive.

A ToggleSplitButton control has two parts that can be invoked separately. One part behaves like a toggle button that can be on or off. The other part invokes a flyout that contains additional options that the user can choose from.

A toggle split button is typically used to enable or disable a feature when the feature has multiple options that the user can choose from. For example, in a document editor, it could be used to turn lists on or off, while the drop down is used to choose the style of the list.

When invoked with touch, the toggle split button behaves as a drop down button. With other methods of input, a user can toggle and invoke the two halves of the button separately. With touch, both halves of the button invoke the flyout. Therefore, you must include an option in your flyout content to toggle the button on or off.

Differences with ToggleButton

Unlike ToggleButton, ToggleSplitButton does not have an indeterminate state. As a result, you should keep in mind these differences:

• ToggleSplitButton does not have an IsThreeState property or Indeterminate event.
• The ToggleSplitButton.IsChecked property is just a Boolean, not a Nullable.
• ToggleSplitButton has only the IsCheckedChanged event; it does not have separate Checked and Unchecked events.

Example — Toggle split button

The following example shows how a toggle split button could be used to turn list formatting on or off, and change the style of the list, in a RichEditBox control. (For more info and code, see Rich edit box). The flyout of the toggle split button uses BottomEdgeAlignedLeft as the default value for its Placement property. You can’t override this value.

Recommendations

Make sure the purpose and state of a button are clear to the user.

When there are multiple buttons for the same decision (such as in a confirmation dialog), present the commit buttons in this order, where [Do it] and [Don’t do it] are specific responses to the main instruction:

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.

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.

Recommended single-button layout

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 be automatically right-aligned.

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.

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.

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 Navigation history and backwards navigation for Windows apps.