Type Function
Library media.*
Return value none
Revision 2016.2887
Keywords media, camera, photo
See also media.hasSource()


Opens a platform-specific interface to the device's photo library. This function is asynchronous, meaning that it returns immediately so the calling code will continue to execute until the end of its scope; after that, the application will be suspended until the session is complete. By default, the image object is added to the top of the current stage, although there is an option to save the image to a directory instead.



This API is not supported on Windows Desktop or Windows Phone.


Some Android app/device combinations require you to add the android.permission.READ_EXTERNAL_STORAGE permission. As of Corona daily build 2016.2825, this permission is required regardless of the Android app/device combination.


The iPad requires the additional parameters of origin and permittedArrowDirections to specify the location and direction of the popup used to select the photo.


media.selectPhoto ( { listener [, mediaSource] [, destination] [, origin] [, permittedArrowDirections] } )
listener (required)

Listener. Can be either a function listener or a table listener. If a table, it must have a completion method. The event dispatched to the listener will be a completion event with the following additional properties:

  • is a DisplayObject based on the mediaSource parameter. If the chosen image is saved to a file, there is no display object added to the stage and this value will be nil.
  • event.completed will be true if the user selected a photo; false if the user cancelled the camera or photo selection.

    media.selectPhoto( { listener=sessionComplete } )

mediaSource (optional)

Constant. Can be one of the following:

  • media.PhotoLibrary
  • media.SavedPhotosAlbum
destination (optional)

Table. If provided, the chosen image is saved to a file. In this case, there is no DisplayObject added to the stage. This table should be in the form { [baseDir= ,] filename= }. If baseDir is specified, this is the directory constant to which to save the file.

origin (optional)

Table. Only applicable on iPad. Defines the bounds of the object (typically a button) from which the iPad's popup emerges from. A convenience pattern is to pass the contentBounds property of the object.

permittedArrowDirections (optional)

Table. Only applicable on iPad. An array of values which defines the directions in which the iPad's popup arrow may point. Valid values are "up", "down", "left", "right", or "any". The default is "any".


local function onComplete( event )
   local photo =
   print( "photo w,h = " .. photo.width .. "," .. photo.height )

if media.hasSource( media.PhotoLibrary ) then
   media.selectPhoto( { mediaSource=media.PhotoLibrary, listener=onComplete } )
   native.showAlert( "Corona", "This device does not have a photo library.", { "OK" } )
-- Selection completion listener
local function onComplete( event )
    local photo =

    if photo then
        print( "photo w,h = " .. photo.width .. "," .. photo.height )

local button = display.newRect( 120, 240, 80, 70 )

local function pickPhoto( event )

        mediaSource = media.SavedPhotosAlbum,
        listener = onComplete, 
        origin = button.contentBounds, 
        permittedArrowDirections = { "right" },
        destination = { baseDir=system.TemporaryDirectory, filename="image.jpg" } 

button:addEventListener( "tap", pickPhoto )