Type Function
Library native.*
Return value WebView
Revision Current Public Release (2017.3068)
Keywords web view, website, web overlay
See also native.showWebPopup()


Loads a web page in a web view container. This native web view can be moved via x/y properties in the same manner as other display objects. On iOS, you can also rotate it via the rotation property.

This API supports loading from either a local file containing HTML content (in one of the system directories) or from a remote website.



  • Native web views are not part of the OpenGL canvas and do not obey the display object hierarchy, so they will always appear in front of normal display objects including images, text, and vector objects.

  • This API should not be confused with the similar (older) native.showWebPopup().

  • You must close a web view by calling the removeSelf() method, because returning false in the listener function has no effect (with web popups, which are different from web views, returning false in the listener closes the web popup—this is not the case with native web views).

  • Native web views are not supported on tvOS and Windows Phone.

  • Native web views can only be rotated via the rotation property on iOS.


On iOS, when checking for event.errorMessage in a web view listener, you may occasionally receive an error message such as NSURLerrorDomain error -999. This is returned when an asynchronous load is cancelled. A Web Kit framework delegate will receive this error when it performs a cancel operation on a loading resource, however a NSURLConnection or NSURLDownload delegate will not receive this error if the download is cancelled. This event/error may occur if a link within web view is clicked while the web view is still in the process of loading the first page. Generally speaking, this error can be ignored.


  • If the web popup is displaying web pages from the Internet, then you must add the INTERNET permission to the build.settings file. This permission is unnecessary if the web view will only be displaying local HTML files that do not access the Internet.
settings =
    android =
        usesPermissions =


native.newWebView( centerX, centerY, width, height )
centerX, centerY (required)

Numbers. The center x and y starting position of the web view.

width, height (required)

Numbers. The width/height of the web view object (in pixels).

Properties / Methods

See the WebView documentation for a list of methods and properties.


See the urlRequest event documentation for properties related to various WebView object events.


Basic Web View
local webView = native.newWebView( display.contentCenterX, display.contentCenterY, 320, 480 )
webView:request( "" )
-- or
webView:request( "localfile.html", system.ResourceDirectory )
Same + Response From Callback Listener
local function webListener( event )
    if event.url then
        print( "You are visiting: " .. event.url )
    if event.type then
        print( "The event.type is " .. event.type ) -- print the type of request
    if event.errorCode then
        native.showAlert( "Error!", event.errorMessage, { "OK" } )
local webView = native.newWebView( display.contentCenterX, display.contentCenterY, 320, 480 )
webView:request( "" )
webView:addEventListener( "urlRequest", webListener )