Type Function
Library transition.*
Return value Object
Revision Current Public Release (2015.2731)
Keywords easing, animation, transition, tween, interpolation
See also Transitions/Tweens (guide)


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.

time (optional)

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

iterations (optional)

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

tag (optional)

String. Specifies the transition tag. The transition library can pause, resume, or cancel transitions sharing the same tag.

transition (optional)

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

delay (optional)

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

delta (optional)

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

onStart (optional)

Listener. A listener called before the transition begins.

onComplete (optional)

Listener. A listener called after the transition completes.

onPause (optional)

Listener. A listener called when the transition is paused.

onResume (optional)

Listener. A listener called when the transition is resumed.

onCancel (optional)

Listener. A listener called when the transition is cancelled.

onRepeat (optional)

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

x, y (optional)

Numbers. Moves the target from its current x/y coordinate to another.

rotation (optional)

Number. Rotates the target from its current angle to another.

alpha (optional)

Number. Fades the target from its current alpha value to another.

xScale, yScale (optional)

Numbers. Scales the target to a specific x ratio or y ratio.

width, height (optional)

Numbers. Resizes the target from its current width/height to another.

x1, y1, x2, y2, x3, y3, x4, y4 (optional)

Numbers. Applies only if the target is a RectPath, applicable to a ShapeObject. These properties control the quadrilateral distortion of the target.

[filterParameter] (optional)

Number. Applicable only if the target is a fill.effect applied to a ShapeObject. In this case, [filterParameter] indicates an effect property associated with the specific filter effect, for example ShapeObject.fill.effect.intensity. See the Filters, Generators, Composites guide for which filter parameters apply to each filter.


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 } )