Usage
Typescript Import Format
//This namespace exports multiple static methods or members. To import
import * as AnimationUtils from "ojs/ojanimation";
//Now you can access the methods as AnimationUtils.methodName and so on
For additional information visit:
Styling Classes
-
.oj-animation-backface
-
Used by the AnimationUtils.flipIn and AnimationUtils.flipOut methods when the
flipTarget
option is set to "children".In this use case, the children of an element represent the two faces of a card. The child element that represents the back face must have the
oj-animation-backface
marker class.
Methods
-
(static) animateHero(element, options) : {Promise.<boolean>}
-
Animation effect method for animating a hero element from one location to another. A hero element is an element that appears to be shared between a source location and a destination location, even though there are separate source element and destination element.
The following steps are taken by this method:
- Create a temporary div that has a z-index higher than that of the source and destination elements.
- Clone the source element.
- Position the cloned element on the temporary div at the same position as the source element.
- Hide the source and destination elements.
- Animate the cloned element by translating and scaling its position and size towards the destination element.
- Show the destination element.
- Remove the temporary div together with the cloned element that is on it.
Parameters:
Name Type Description element
Element The source element for the hero animation. options
Object Options applicable to the specific animation effect. Properties
Name Type Argument Description toElementSelector
string A CSS selector which specifies the destination element that occupies the location to animate to. toElementWaitTime
number <optional>
The time in millisecond to wait for the destination element to become present in the DOM tree. The default is 5000, which is equal to 5 seconds. No animation occurs and the promise returned by this function will be rejected if the destination element is not present when toElementWaitTime expires. createClonedElement
function(AnimationUtils.HeroContext):Element <optional>
An optional application-provided function that returns the element used in animation. By default animateHero will clone the source element specified by the "fromElement" parameter. Application can override this by returning a different element.
hideFromAndToElements
function(AnimationUtils.HeroContext):void <optional>
An optional application-provided function that controls the visibility of the source and destination elements during animation. By default animateHero will hide both the source element and destination element while animating the cloned element.
animateClonedElement
function(AnimationUtils.HeroContext):Promise <optional>
An optional application-provided function that animates the cloned element. By default animateHero will move and scale the cloned element to the position and size of the destination element.
showToElement
function(AnimationUtils.HeroContext):void <optional>
An optional application-provided function that controls the visibility of the destination element after animation. By default animateHero will show the destination element after animation ends.
delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) collapse(element, options) : {Promise.<boolean>}
-
Animaton effect method for collapsing a HTML element.
When using this method to hide an element, the element should not have any border or padding, because border and padding are visible even if the element's height is set to 0. The use of "box-sizing: border-box" style doesn't change this behavior. If the element needs border and padding, create a wrapper element around it and call this method on the wrapper element instead.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". direction
string <optional>
direction to collapse. Valid values are "height", "width", or "both". Default is "height". startMaxHeight
string <optional>
starting max-height value to collapse from. Default is natural element height. endMaxHeight
string <optional>
ending max-height value to collapse to. Default is "0". startMaxWidth
string <optional>
starting max-width value to collapse from. Default is natural element width. endMaxWidth
string <optional>
starting max-width value to collapse to. Default is "0". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) expand(element, options) : {Promise.<boolean>}
-
Animaton effect method for expanding a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". direction
string <optional>
direction to expand. Valid values are "height", "width", or "both". Default is "height". startMaxHeight
string <optional>
starting max-height value to expand from. Default is "0". endMaxHeight
string <optional>
ending max-height value to expand to. Default is natural element height. startMaxWidth
string <optional>
starting max-width value to expand from. Default is "0". endMaxWidth
string <optional>
starting max-width value to expand to. Default is natural element width. Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) fadeIn(element, options) : {Promise.<boolean>}
-
Animaton effect method for fading in a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". startOpacity
number <optional>
starting opacity. Default is 0. endOpacity
number <optional>
ending opacity. Default is 1. Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) fadeOut(element, options) : {Promise.<boolean>}
-
Animaton effect method for fading out a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". startOpacity
number <optional>
starting opacity. Default is 1. endOpacity
number <optional>
ending opacity. Default is 0. Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) flipIn(element, options) : {Promise.<boolean>}
-
Animaton effect method for rotating a HTML element into view.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". axis
string <optional>
The axis of the rotation. Valid values are "x" and "y". Default is "y". startAngle
string <optional>
The starting angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "-180deg", which shows the back face of the element. endAngle
string <optional>
The ending angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "0deg", which shows the front face of the element. backfaceVisibility
string <optional>
The visibility of the back face when facing the user. Valid values are "visible" and "hidden". If set to "visible", the back face shows a mirrored image of the front face. If set to "hidden", the back face is invisible. Default is "hidden". perspective
string <optional>
The 3D perspective for the element. Default is "2000px". A smaller value makes the 3D effect more pronounced during rotation. transformOrigin
string <optional>
The axis location for the rotation. Refer to CSS transform-origin for valid values. Default is "center". flipTarget
string <optional>
The target for flipping. Valid values are "element" and "children". Default is "element". Set to "element" to flip the element itself.
Set to "children" to flip the children of the element. This is used when the element is a card-like structure that has children to represent the front and back faces of a card. The child that represents the back face must have the "oj-animation-backface" marker class. Use this option instead of the "transform-style: preserve-3d" CSS style because some browsers do not support "transform-style". See the cookbook for a Card Flip example of using this option.
Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) flipOut(element, options) : {Promise.<boolean>}
-
Animaton effect method for rotating a HTML element out of view.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". axis
string <optional>
The axis of the rotation. Valid values are "x" and "y". Default is "y". startAngle
string <optional>
The starting angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "0deg", which shows the front face of the element. endAngle
string <optional>
The ending angle of the rotation. Refer to CSS rotate() transform for valid values. Default is "180deg", which shows the back face of the element. backfaceVisibility
string <optional>
The visibility of the back face when facing the user. Valid values are "visible" and "hidden". If set to "visible", the back face shows a mirrored image of the front face. If set to "hidden", the back face is invisible. Default is "hidden". perspective
string <optional>
The 3D perspective for the element. Default is "2000px". A smaller value makes the 3D effect more pronounced during rotation. transformOrigin
string <optional>
The axis location for the rotation. Refer to CSS transform-origin for valid values. Default is "center". flipTarget
string <optional>
The target for flipping. Valid values are "element" and "children". Default is "element". Set to "element" to flip the element itself.
Set to "children" to flip the children of the element. This is used when the element is a card-like structure that has children to represent the front and back faces of a card. The child that represents the back face must have the "oj-animation-backface" marker class. Use this option instead of the "transform-style: preserve-3d" CSS style because some browsers do not support "transform-style". See the cookbook for a Card Flip example of using this option.
Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) ripple(element, options) : {Promise.<boolean>}
-
Animaton effect method for rippling a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". offsetX
string <optional>
Horizontal offset of the ripple center, with a unit of either "px" or "%". If the unit is "px", it specifies the offset in pixels. If the unit is "%", it specifies the offset as a percentage of the element's width. offsetY
string <optional>
Vertical offset of the ripple center, with a unit of either "px" or "%". If the unit is "px", it specifies the offset in pixels. If the unit is "%", it specifies the offset as a percentage of the element's height. color
string <optional>
Color of the ripple. Default is specified in the "oj-animation-effect-ripple" CSS class. diameter
string <optional>
Diameter of the ripple, with a unit of either "px" or "%". If the unit is "px", it specifies the diameter in pixels. If the unit is "%", it specifies the diameter as a percentage of either the element's width or height, whichever is less. Default is specified in the "oj-animation-effect-ripple" CSS class. startOpacity
number <optional>
start opacity of the ripple. Default is specified in the "oj-animation-effect-ripple" CSS class. endOpacity
number <optional>
end opacity of the ripple. Default is 0. Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) slideIn(element, options) : {Promise.<boolean>}
-
Animaton effect method for sliding in a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". direction
string <optional>
Direction of the slide. Valid values are "left", "top", "right", "bottom", "start", and "end". Default is "start". This option is ignored if either offsetX or offsetY is specified. offsetX
string <optional>
The offset on the x-axis to translate from. This value must be a number followed by a unit such as "px", "em", etc. If moving in a horizontal direction, default to element width. Otherwise, default to "0px". offsetY
string <optional>
The offset on the y-axis to translate from. This value must be a number followed by a unit such as "px", "em", etc. If moving in a vertical direction, default to element height. Otherwise, default to "0px". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) slideOut(element, options) : {Promise.<boolean>}
-
Animaton effect method for sliding out a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". direction
string <optional>
Direction of the slide. Valid values are "left", "top", "right", "bottom", "start", and "end". Default is "start". This option is ignored if either offsetX or offsetY is specified. offsetX
string <optional>
The offset on the x-axis to translate to. This value must be a number followed by a unit such as "px", "em", etc. If moving in a horizontal direction, default to element width. Otherwise, default to "0px". offsetY
string <optional>
The offset on the y-axis to translate to. This value must be a number followed by a unit such as "px", "em", etc. If moving in a vertical direction, default to element height. Otherwise, default to "0px". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) zoomIn(element, options) : {Promise.<boolean>}
-
Animaton effect method for zooming in a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". axis
string <optional>
the axis along which to scale the element. Valid values are "x", "y", or "both". Default is "both". transformOrigin
string <optional>
set the CSS transform-origin property, which controls the anchor point for the zoom. Default is "center". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
-
(static) zoomOut(element, options) : {Promise.<boolean>}
-
Animaton effect method for zooming out a HTML element.
Parameters:
Name Type Argument Description element
Element the HTML element to animate options
Object <optional>
Options applicable to the specific animation effect. Properties
Name Type Argument Description delay
string <optional>
The delay from the time the animation is applied to time the animation should begin. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "0s". duration
string <optional>
The duration that an animation should take to complete. This may be specified in either seconds (by specifying s as the unit) or milliseconds (by specifying ms as the unit). Default is "400ms". timingFunction
string <optional>
One of the valid values for either CSS transition-timing-function or CSS animation-timing-function. Default is "ease". persist
string <optional>
Valid values are "none" and "all". Set to "none" to remove the inline style being animated at the end of animation. Set to "all" to persist the inline style. Default is "none". axis
string <optional>
the axis along which to scale the element. Valid values are "x", "y", or "both". Default is "both". transformOrigin
string <optional>
set the CSS transform-origin property, which controls the anchor point for the zoom. Default is "center". Returns:
a promise that will be resolved when the animation ends
- Type
- Promise.<boolean>
Type Definitions
-
AnimationMethods
-
All the available animation methods supported in AnimationUtils
Supported Values:
Value collapse
expand
fadeIn
fadeOut
flipIn
flipOut
ripple
slideIn
slideOut
zoomIn
zoomOut
-
HeroContext
-
The context object passed to callback functions in the animateHero method
Properties:
Name Type Description clonedElement
Element | null The cloned element. This property is null when createClonedElement is called. It will be the value returned by createClonedElement in other callback functions. fromElement
Element The source element scaleX
number The horizontal size ratio of the toElement to the fromElement scaleY
number The vertical size ratio of the toElement to the fromElement toElement
Element The destination element toElementElapsedTime
number The elapsed time in millisecond that the destination element becomes present in the DOM tree after animateHero is called. If desired, applications can use this information to adjust the animation. For example, if the destination element takes a long time to appear, a shorter animation may be used. translateX
number The x offset of the toElement from the fromElement translateY
number The y offset of the toElement from the fromElement