VisualStateGroup VisualStateGroup VisualStateGroup VisualStateGroup Class


Contains mutually exclusive VisualState objects and VisualTransition objects that are used to go from one state to another.

public : sealed class VisualStateGroup : DependencyObject, IVisualStateGroup
struct winrt::Windows::UI::Xaml::VisualStateGroup : DependencyObject, IVisualStateGroup
public sealed class VisualStateGroup : DependencyObject, IVisualStateGroup
Public NotInheritable Class VisualStateGroup Inherits DependencyObject Implements IVisualStateGroup
   <VisualStateGroup x:Name="groupname" ...>
   <!--- other peer VisualStateGroup's here ... -->
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)


This example creates a simple ControlTemplate for a Button that contains one Grid. It also contains a VisualStateGroup called "CommonStates", which defines the "PointerOver" and "Normal" states. The VisualStateGroup also has a VisualTransition that specifies that it takes one half second for the Grid to change from green to red when the user puts the pointer over the Button.

<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"/>


Each VisualStateGroup declared in XAML as part of a control template should always have an x:Name attribute set on it. Each name string used in the set of VisualStateGroups in a control template must be unique in that template. It's common to use the same group names for different controls though. For example, almost all existing control templates have a VisualStateGroup with x:Name attribute of "CommonStates".

The set of visual states within each VisualStateGroup should be mutually exclusive in the group. In other words, the control should be using exactly one of the visual states from each of its defined VisualStateGroup groups at all times. Whenever there's a case where a control is intended to be simultaneously in two states, make sure that the two states are in different groups. For example, it's possible for a drop-down control to simultaneously be focused and have its drop-down open. In a correct visual state design, you'd have a separate VisualStateGroup for each state so they can both be active at once. Such groups might have names like "FocusStates" and "DropDownStates".

Whenever you define a VisualStateGroup that enables a temporary storyboarded behavior in one of its VisualState elements, make sure that group also contains a second VisualState that can be called to cancel the previous state. This can be as simple as declaring the second VisualState with no Storyboard at all, just an x:Name attribute.

The x:Name attribute value you set for a VisualStateGroup is not used for a call to VisualStateManager.GoToState; instead it's the x:Name attribute of a VisualState that is used for VisualStateManager.GoToState. Anyone that uses VisualStateManager.GoToState should be aware of all the groups and states available, so that each call correctly transitions from old states to new states within a group.

In addition to a set of VisualState elements, a VisualStateGroup can also define a set of VisualTransition elements, where each VisualTransition pertains to at least one of the named VisualState elements defined in the group. In XAML, the set of VisualState elements can be declared as immediate object element child elements of the VisualStateGroup. This is possible because the States property, which is the collection of visual states, is the XAML content property for VisualStateGroup. In contrast, to set the collection of visual transitions, you must declare that collection within a VisualStateGroup.Transitions property element in XAML. For more info on XAML content properties, see XAML syntax guide.

VisualStateGroup API that support custom VisualStateManager implementation

Many of the API of VisualStateGroup exist only to support custom VisualStateManager implementation. These include: Name, CurrentState, CurrentStateChanging, CurrentStateChanged. Most common usages of visual states for control templates won't need these API. In particular it's not typical to handle the events. Most logic operations for a control should involve its own properties and events. For most app and control definition scenarios, visual state changes that happen to the control should only be an end result of logic that the control applies to its template, not a trigger for other logic.


VisualStateGroup() VisualStateGroup() VisualStateGroup() VisualStateGroup()

Initializes a new instance of the VisualStateGroup class.

public : VisualStateGroup()
VisualStateGroup() const;
public VisualStateGroup()
Public Sub New()


CurrentState CurrentState CurrentState CurrentState

Gets the most recently set VisualState from a successful call to the GoToState method.

public : VisualState CurrentState { get; }
VisualState CurrentState();
public VisualState CurrentState { get; }
Public ReadOnly Property CurrentState As VisualState
VisualState VisualState

The most recently set VisualState from a successful call to the GoToState method, or null.


If GoToState has never been called for the states in a particular VisualStateGroup, CurrentState is null. With correct design of controls and visual state, this shouldn't happen. The control logic for a control should always be able to select one state from a given VisualStateGroup, even if that state is a named state with no specific storyboarded behavior.

Because there are potentially multiple VisualStateGroup sets of visual states for a control, each such VisualStateGroup can report a CurrentState. For example, if you click on a Button with a default control template, the "CommonStates" VisualStateGroup reports a CurrentState of "Pressed", and the "FocusStates" VisualStateGroup reports a CurrentState of "PointerFocused".

See Also

Dispatcher Dispatcher Dispatcher Dispatcher

Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.

(Inherited from DependencyObject)

Name Name Name Name

Gets the name of the VisualStateGroup.

public : Platform::String Name { get; }
winrt::hstring Name();
public string Name { get; }
Public ReadOnly Property Name As string
<VisualStateGroup x:Name="groupName"/>
string string

The name of the VisualStateGroup.


Name is a read-only property that you can check with code at run-time to read the value of the x:Name attribute that was applied to a VisualStateGroup in a XAML control template. You can't literally set Name because it's read-only, and x:Name attribute can only be set in XAML. The value is available as soon as the XAML that contains the control template and the VisualStateGroup definition is loaded.

The need to check the Name of a VisualStateGroup at run-time is anticipated to be relatively uncommon, and would only be relevant to advanced scenarios. For the most part, the definition of a VisualStateGroup in XAML combined with using VisualStateManager and VisualStateGroup events in code provides you all that you need to define and invoke visual states for a custom or Windows Runtime-defined control.

See Also

States States States States

Gets the collection of mutually exclusive VisualState objects.

public : IVector<VisualState> States { get; }
IVector<VisualState> States();
public IList<VisualState> States { get; }
Public ReadOnly Property States As IList<VisualState>
IList<VisualState> IList<VisualState>

The collection of mutually exclusive VisualState objects.

Transitions Transitions Transitions Transitions

Gets the collection of VisualTransition objects.

public : IVector<VisualTransition> Transitions { get; }
IVector<VisualTransition> Transitions();
public IList<VisualTransition> Transitions { get; }
Public ReadOnly Property Transitions As IList<VisualTransition>
IList<VisualTransition> IList<VisualTransition>

The collection of VisualTransition objects.


CurrentStateChanged CurrentStateChanged CurrentStateChanged CurrentStateChanged

Occurs after a control changes into a different state.

public : event VisualStateChangedEventHandler CurrentStateChanged<>
// Register
event_token CurrentStateChanged(VisualStateChangedEventHandler<> const& handler) const;

// Revoke with event_token
void CurrentStateChanged(event_token const& cookie) const;

// Revoke with event_revoker
CurrentStateChanged_revoker CurrentStateChanged(auto_revoker_t, VisualStateChangedEventHandler<> const& handler) const;
public event VisualStateChangedEventHandler CurrentStateChanged<>
Public Event VisualStateChangedEventHandler CurrentStateChanged( Of )

CurrentStateChanging CurrentStateChanging CurrentStateChanging CurrentStateChanging

Occurs when a control begins changing into a different state.

public : event VisualStateChangedEventHandler CurrentStateChanging<>
// Register
event_token CurrentStateChanging(VisualStateChangedEventHandler<> const& handler) const;

// Revoke with event_token
void CurrentStateChanging(event_token const& cookie) const;

// Revoke with event_revoker
CurrentStateChanging_revoker CurrentStateChanging(auto_revoker_t, VisualStateChangedEventHandler<> const& handler) const;
public event VisualStateChangedEventHandler CurrentStateChanging<>
Public Event VisualStateChangedEventHandler CurrentStateChanging( Of )


ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Clears the local value of a dependency property.

(Inherited from DependencyObject)

GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty)

Returns any base value established for a dependency property, which would apply in cases where an animation is not active.

(Inherited from DependencyObject)

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Returns the current effective value of a dependency property from a DependencyObject.

(Inherited from DependencyObject)

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Returns the local value of a dependency property, if a local value is set.

(Inherited from DependencyObject)

RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance.

(Inherited from DependencyObject)

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Sets the local value of a dependency property on a DependencyObject.

(Inherited from DependencyObject)

UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.

(Inherited from DependencyObject)

See Also