Represents the period of time that a Timeline object is active.

<object property="durationString" .../>




Example result

Time span



Start to end is 15 seconds.

Literal "Automatic"



See Remarks.

Literal "Forever"



See Remarks.

  • In the grammar above, square brackets ([]) indicate optional values; the brackets are not literals. The colon (:) and period (.) characters are both literals.

  • Values for hours can be any integer value from 0 through 23. Values for minutes and seconds can be any integer value from 0 through 59. The value for days can be very large, but it does have an unspecified upper bound. The decimal value for fractionalSeconds (with the decimal point included) must be between 0 and 1.

  • Automatic and Forever are literal strings that hold special meaning for a Duration.

You can create a Duration, KeyTime, RepeatBehavior, or TimeSpan object in XAML or in script only through a type conversion syntax when you set a property (such as Duration (Timeline)) that takes one of these types, with the value specified as a string. The string format for specifying a time span in each of these types is identical. Duration can also take the literals "Automatic" and "Forever". RepeatBehavior can take the literal "Forever" and also an iterations syntax "#x".

The main scenario for working with a Duration as an object in script is to get or set its Seconds property to query or change an existing animation value.

The typical time span of an animation is in seconds. Therefore, the Duration string would include preceding 0 values for hours and minutes, along with the appropriate literal characters—colons (:) and periods (.)—as separators between hours, minutes, seconds, and fractions of seconds. For example, to specify a Duration of 5 seconds, you would set the Duration string to "0:0:5" ("0:0:05" is equivalent).

Important noteImportant Note:

If you specify a Duration by an integer without any time span literal characters—colons (:) or periods (.)—the integer will be interpreted only as a number of days. This is seldom the intended result and will typically cause the Duration to be unexpectedly large.

You can set the Duration on either a Storyboard or an animation. The Automatic literal value results in different behavior for these two cases. For a Storyboard, the Automatic duration behavior is equal to the end time of its latest ending child animation, such that no clipping of any of the child animation durations occurs. For animations, the Automatic duration is a time span of 1 second. This short duration is seldom desirable, but this default at least provides you the opportunity to see the animation start during testing, which provides better debugging information than never having the animation run.

A Duration of Forever for an animation is deprecated and is seldom used. A Duration of Forever would result in an animation that never advanced from its starting value, no matter what values were provided for From, To, key frames, and so on.

For more information on basic concepts, see Animation Overview. Note that the Animation Overview topic is written primarily for users of the managed API, and may not have code examples or specific information that address the JavaScript API scenarios.

Community Additions