Transition events inform you of the changes in a transition’s state.
UI Toolkit uses transitions when a VisualElement
’s property is modified. Changes to VisualElement
property are immediately reflected visually. However, you can use the transition
USS property to interpolate between the initial and end results gradually.
A transition’s lifecycle has the following stages:
A VisualElement
’s property is modified when you:
element.ToggleInClassList()
(where element
is any VisualElement
).:hover
.style
property. For example: element.style.backgroundColor = Color.red;
(where element
is any VisualElement
).A TransitionRunEvent
is sent.
If the resolved transition-delay
property for the changing property has a value other than 0
, nothing happens for the duration of the delay.
After the delay, a TransitionStartEvent
is sent, and the transition starts with the property at its initial value.
For the length of time set by transition-duration
, the transition occurs. During that time, the property goes from its initial to its final value.
If the property is changed to a new value during the transition, TransitionCancelEvent
is sent. The transition process restarts at step 2.
After the transition-duration
elapses, the property sets to its final value. A TransitionEndEvent
is sent.
The following table describes the transition events and their propagation phases:
Event | Description | Trickles down | Bubbles up | Cancellable |
---|---|---|---|---|
TransitionRunEvent | Sent when a transition is created. | Yes | ||
TransitionStartEvent | Sent when a transition’s delay phase ends and the transition starts. | Yes | ||
TransitionEndEvent | Sent when a transition ends. | Yes | ||
TransitionCancelEvent | Sent when an a transition is canceled. | Yes |
Each transition property has its own lifecycle and its own transition events. You can access the current property with an event’s stylePropertyNames
property.
If a shorthand USS property is changed, every component also gets its own lifecycle. For example, if you change margin
, margin-left
, margin-right
, margin-top
and margin-bottom
, they all get their own TransitionRunEvent
, TransitionStartEvent
and TransitionEndEvent
, for a total of 12 separate events.
If you set transition-delay
to 0
, the TransitionRunEvent
and TransitionStartEvent
are sent one after the other within a few milliseconds.
If you set transition-delay
to a value below 0
, the transition won’t start at the beginning. For example, with a transition-delay
of -3
seconds and transition-duration
of 5
seconds, the TransitionRunEvent
and TransitionStartEvent
is sent with an elapsedTime
property set to 3
seconds and the transition effectively starts at the third second of a five-second animation.
This section describes the target
, stylePropertyNames
, and elapsedTime
of each transition event.
A TransitionRunEvent
event is sent when a transition is created.
target
: The element that executes the transition.stylePropertyNames
: The list of properties modified by the transition.elapsedTime
: The time since the start of the transition.A TransitionStartEvent
event is sent when the transition’s delay phase ends and the transition begins.
target
: The element that executes the transition.stylePropertyNames
: The list of properties modified by the transition.elapsedTime
: The time since the start of the transition.A TransitionEndEvent
event is sent when a transition ends.
target
: The element that executes the transition.stylePropertyNames
: The list of properties modified by the transition.elapsedTime
: The time since the start of the transition.A TransitionCancelEvent
event is sent when a transition is interrupted by the property being changed again.
target
: The element that executes the transition.stylePropertyNames
: The list of properties modified by the transition.elapsedTime
: The time since the start of the transition.TransitionEndEvent
to create transitions that loop.