How to add a toggle switch (XAML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

This tutorial walks you through the steps to add a toggle switch to a Windows Runtime app using C++, C#, or Visual Basic.

You typically add a toggle switch in the Extensible Application Markup Language (XAML) editor or using a design tool like Blend for Visual Studio. You can also add a toggle switch in code at runtime.

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

What you need to know

Technologies

• CheckBox

Prerequisites

• We assume that you can add controls to a basic Windows Runtime app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.

Instructions

Step 1: Add a toggle switch in XAML

To add a toggle switch in XAML

1. Add a ToggleSwitch control to a parent container.

2. To assign a name to the toggle switch, set the x:Name attribute to a string value.

   To refer to a control in code, it must have a name. Otherwise, a name is not required.

3. To assign a header to the toggle switch, set the Header property to a string value.

4. To assign a label to show when the toggle switch is on, set the OnContent property to a string value.

5. To assign a label to show when the toggle switch is off, set the OffContent property to a string value.

6. To perform an action when the toggle switch state changes, add a handler for the Toggled event. In the Toggled event handler, add code to perform some action.

   <ToggleSwitch x:Name="toggleSwitch1" Header="ToggleSwitch" 
                 OnContent="On" OffContent="Off" 
                 Toggled="ToggleSwitch_Toggled"/>
   

   void MainPage::ToggleSwitch_Toggled(Object^ sender, RoutedEventArgs^ e)
   {
       // Add code to perform some action here.
   }
   

   private void ToggleSwitch_Toggled(object sender, RoutedEventArgs e)
   {
       // Add code to perform some action here.
   }
   

   Private Sub ToggleSwitch_Toggled()
       ' Add code to perform some action here.
   End Sub
   

   To check the state of the control outside of the Toggled event, use the IsOn property.

Step 2: Add a toggle switch in code

To add a toggle switch in code

1. Create a new ToggleSwitch.

2. To assign a header to the toggle switch, set the Header property to a string value.

3. To assign a label to show when the toggle switch is on, set the OnContent property to a string value.

4. To assign a label to show when the toggle switch is off, set the OffContent property to a string value.

5. To perform an action when the toggle switch state changes, add a handler for the Toggled event. In the Toggled event handler, add code to perform some action.

6. Add the ToggleSwitch to a parent container in the visual tree to make the toggle switch show in the UI.

   // Create a new toggle switch, set it's content, 
   // and add a Toggled event handler.
   ToggleSwitch^ toggleSwitch1 = ref new ToggleSwitch();
   toggleSwitch1->Header = "Toggle Switch";
   toggleSwitch1->OnContent = "On";
   toggleSwitch1->OffContent = "Off";
   toggleSwitch1->Toggled += 
       ref new RoutedEventHandler(this, &MainPage::ToggleSwitch_Toggled);
   
   // Add the toggle switch to a parent container in the visual tree.
   stackPanel1->Children->Append(toggleSwitch1);
   

   // Create a new toggle switch, set it's content, 
   // and add a Toggled event handler.
   ToggleSwitch toggleSwitch1 = new ToggleSwitch();
   toggleSwitch1.Header = "Toggle Switch";
   toggleSwitch1.OnContent = "On";
   toggleSwitch1.OffContent = "Off";
   toggleSwitch1.Toggled += ToggleSwitch_Toggled;
   
   // Add the toggle switch to a parent container in the visual tree.
   stackPanel1.Children.Add(toggleSwitch1);
   

   ' Create a new toggle switch, set it's content, 
   ' and add a Toggled event handler.
   Dim toggleSwitch1 = New ToggleSwitch()
   toggleSwitch1.Header = "Toggle Switch"
   toggleSwitch1.OnContent = "On"
   toggleSwitch1.OffContent = "Off"
   AddHandler toggleSwitch1.Toggled, AddressOf Me.ToggleSwitch_Toggled
   
   ' Add the toggle switch to a parent container in the visual tree.
   stackPanel1.Children.Add(toggleSwitch1)
   

   void MainPage::ToggleSwitch_Toggled(Object^ sender, RoutedEventArgs^ e)
   {
       // Add code to perform some action here.
   }
   

   private void ToggleSwitch_Toggled(object sender, RoutedEventArgs e)
   {
       // Add code to perform some action here.
   }
   

   Private Sub ToggleSwitch_Toggled()
       ' Add code to perform some action here.
   End Sub
   

   To check the state of the control outside of the Toggled event, use the IsOn property.

Step 3: Add a toggle switch using a design tool

To add a toggle switch using a design tool

1. Select the ToggleSwitch control.

   • In Microsoft Visual Studio, pick the ToggleSwitch in the Toolbox pane.

   • In Blend for Visual Studio, pick the ToggleSwitch in the Assets pane.

     Select Controls in the left side of the Assets pane if it's not selected.

2. Add a ToggleSwitch to the design surface. Do one of these:

   • Double-click the toggle switch. The toggle switch is added to the selected parent container with default position and size settings.
   • Drag the toggle switch to the design surface and drop it. The toggle switch is added in the position where you drop it with default size and content settings.
   • Draw the toggle switch control onto the design surface. The toggle switch is added with the size and position settings that you draw.

3. If you need to, assign a name to the ToggleSwitch. With the toggle switch selected, type the name into the Name property text box.

   The Name property text box is at the top of the Properties pane. To refer to a control in code, it must have a name. Otherwise, a name is not required.

4. Update the ToggleSwitch header. With the toggle switch selected, type the content string into the Header property text box.

   If the Properties pane is arranged by Category, the Header property is in the Common category.

5. If you need to, update the label to show when the ToggleSwitch is on. With the toggle switch selected, type the content string into the OnContent property text box.

   If the Properties pane is arranged by Category, the OnContent property is in the Common category. The default value is "On".

6. If you need to, update the label to show when the ToggleSwitch is off. With the toggle switch selected, type the content string into the OffContent property text box.

   If the Properties pane is arranged by Category, the OffContent property is in the Common category. The default value is "Off".

7. To perform an action when the toggle switch state changes, add a handler for the Toggled event. In the Toggled event handler, add code to perform some action.

   1. Select the Event view in the Property pane.
   2. With the toggle switch selected on the design surface, do one of these:
      • Double click the Toggled event text box to add a handler with a default name.
      • Type a name into the Toggled event text box and press Enter to add a handler with a custom name.

Related topics

ToggleSwitch

Guidelines and checklist for toggle switches

Roadmap for Windows Runtime apps using C# or Visual Basic

Roadmap for Windows Runtime apps using C++