Type Function
Library transition.*
Return value Object
Revision 2014.2382
Keywords easing, animation, transition, tween, interpolation
See also Transitions/Tweens


Animates (transitions) a display object using an optional easing algorithm. Use this to move, rotate, fade, or scale an object over a specific period of time.

This function returns a reference corresponding to the transition/animation of the object target.

Please see the Transitions/Tweens guide for usage information.

Syntax target, params )
target (required)

Table. Any object that behaves like a table, for example display objects.

params (required)

Table. A table that specifies the properties of the transition — see the next section for details.

Parameter Reference

The params table includes the properties of target that should be interpolated.

params.time (optional)

Number. Specifies the duration of the transition in milliseconds. By default, the duration is 500 milliseconds.

params.iterations (optional)

Number. Specifies the number of iterations for which the transition will repeat. By default, the iteration value is 1.

params.tag (optional)

String. Specifies the transition tag. The transition library can pause, resume, or cancel transitions by tag name.

params.transition (optional)

Function. Specifies the easing interpolation method. Default is linear.

params.delay (optional)

Number. Specifies the delay, in milliseconds, before the transition begins. Default is 0. (optional)

Boolean. Specifies whether non-control parameters are interpreted as final ending values or as changes in value. The default is false.

params.onStart (optional)

Listener. A listener called before the transition begins. Table listeners must have an onStart method.

params.onComplete (optional)

Listener. A listener called after the transition completes. The transition object is available in the listener call.

params.onPause (optional)

Listener. A listener called when the transition is paused.

params.onResume (optional)

Listener. A listener called when the transition is resumed.

params.onCancel (optional)

Listener. A listener called when the transition is cancelled.

params.onRepeat (optional)

Listener. A listener called when the transition completes an iteration in a repeat cycle.


local square = display.newRect( 0, 0, 100, 100 )

local w,h = display.contentWidth, display.contentHeight

local listener1 = function( obj )
    print( "Transition 1 completed on object: " .. tostring( obj ) )

local listener2 = function( obj )
    print( "Transition 2 completed on object: " .. tostring( obj ) )

-- (1) move square to bottom right corner; subtract half side-length square, { time=1500, alpha=0, x=(w-50), y=(h-50), onComplete=listener1 } )

-- (2) fade square back in after 2.5 seconds square, { time=500, delay=2500, alpha=1.0, onComplete=listener2 } )