VisualStateManager.VisualStateGroups attached property

VisualStateManager.VisualStateGroups attached property

Gets the collection of VisualStateGroup elements that are defined by a root element of a template definition. A control typically defines this as part of its template.


XAML Values


The root UIElement as defined within a control template (a ControlTemplate object element).


One or more VisualStateGroup elements. Each such VisualStateGroup is expected to have a unique x:Name within its definition scope. Each VisualStateGroup typically contains at least one VisualState definition.


VisualStateManager supports two important features for control authors, and for app developers who are applying a custom template to a control:

  • Control authors or app developers add VisualStateGroup object elements to the root element of a control template definition in XAML, using the VisualStateManager.VisualStateGroups attached property. Within a VisualStateGroup element, each VisualState represents a discrete visual state of a control. Each VisualState has a name that is representative of a UI state that can be changed by the user, or changed by control logic. A VisualState consists mainly of a Storyboard. This Storyboard targets individual dependency property value changes that should be applied whenever the control is in that visual state.
  • Control authors or app developers transition between these states by calling the static GoToState method of VisualStateManager. Control authors do this whenever the control logic handles events that indicate a change of state, or control logic initiates a state change by itself. It's more common for control definition code to do this rather than app code, so that all the possible visual states and their transitions and trigger conditions are there by default for app code.

Most developers will use just two of the VisualStateManager APIs: VisualStateManager.VisualStateGroups, and GoToState, as described above.

VisualStateManager.VisualStateGroups is an attached property, which supports a XAML usage. When getting this property in code, use GetVisualStateGroups. This returns a collection object, which you can add items to. This parallels the XAML processing behavior of any child elements of a <VisualStateManager.VisualStateGroups> property element usage. Because there is no public dependency property identifier for this particular attached property, you cannot use GetValue to get this attached property value, you always have to use GetVisualStateGroups.

A VisualStateManager.VisualStateGroups value is not interpreted by any tangible VisualStateManager object that is part of the same visual tree. Instead, the property provides a generalized container property that can be used on any possible UIElement that serves as the root element of a template definition.


This example shows how to use the VisualStateManager.VisualStateGroups XAML attached property. Note how there is otherwise no "VisualStateManager" tag defined. Conceptually, VisualStateManager.VisualStateGroups contains the visual states for a control, as an immediate child tag of the template root in a control template.

The particular set of visual states contains one VisualStateGroup, called "CommonStates", which defines the "PointerOver" and "Normal" VisualState objects. When the user puts the pointer over the Button, the Grid changes from green to red over one half second. When the user moves the pointer away from the button, the Grid immediately changes back to green.

<ControlTemplate TargetType="Button">
  <Grid >
      <VisualStateGroup x:Name="CommonStates">


          <!--Take one half second to transition to the PointerOver state.-->
          <VisualTransition To="PointerOver" 
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, ButtonBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
            <ColorAnimation Storyboard.TargetName="ButtonBrush" 
                            Storyboard.TargetProperty="Color" To="Red" />
      <SolidColorBrush x:Name="ButtonBrush" Color="Green"/>

Requirements (Windows 10 device family)

Device family

API contract




Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]





See also

Quickstart: Control templates
Attached properties overview



© 2016 Microsoft