Type Function
Library native.*
Return value TextBox
Revision Current Public Release (2014.2393)
Keywords text box, text input, native text
See also native.newTextField()
userInput events


Creates a scrollable, multi-line text box for displaying text-based content. Text boxes can also be used for text input (and multi-line text input) by setting the isEditable property to true.

Use "" to start text on a new line. Text will automatically wrap to the next line if it's too long.

Native text boxes can listen for userInput events. (see example)



native.newTextBox( centerX, centerY, width, height [, listener ] )
centerX, centerY (required)

Numbers. The x and y coordinates that correspond to the center of the text box.

width, height (required)

Numbers. Width and height (size) of the text box.

listener (optional)

Listener. Function to respond to keyboard events. If you choose to handle this event with a table listener, the event name is "userInput" (recommended). See userInput for more information.


local function inputListener( event )
    if event.phase == "began" then

        -- user begins editing textBox
        print( event.text )

    elseif event.phase == "ended" then

        -- do something with textBox's text

    elseif event.phase == "editing" then

        print( event.newCharacters )
        print( event.oldText )
        print( event.startPosition )
        print( event.text )


local textBox = native.newTextBox( 200, 200, 280, 140 )
textBox.text = "This is line 1.\nAnd this is line2"
textBox.isEditable = true
textBox:addEventListener( "userInput", inputListener )