Type Function
Library display.*
Revision Release 2024.3703
Keywords groups, container
See also Using Containers (guide)


Containers are a special kind of group in which the children are clipped (masked) by the bounds of the container.

See the Using Containers guide for more information.


display.newContainer( [parent,] width, height )


Container objects are created using a mask and there is a nested masking limit of 3. Thus, care must be taken when inserting other masked objects into containers. Display objects that utilize masks include display.newText, display.newEmbossedText, widget.newScrollView, widget.newTableView, other containers, and any other masked image, masked vector object, or masked display group. For example, a text object (one mask) inside a container (one mask) inside yet another container (one mask) would reach but not exceed the limit of 3 nested masks.


-- Create a container
local container = display.newContainer( 128, 128 )

-- Create an image
local bkgd = display.newImage( "aquariumbackgroundIPhone.jpg" )
-- Insert the image into the container
container:insert( bkgd, true )
-- Center the container in the display area
container:translate( display.contentWidth*0.5, display.contentHeight*0.5 )

-- Transition (rotate) the container
transition.to( container, { rotation=360, transition=easing.inOutExpo} )