display.getSafeAreaInsets()

Type Function
Library display.*
Return value Numbers
Revision Release 2022.3683
Keywords safe area, insets
See also display.safeScreenOriginX
display.safeScreenOriginY
display.safeActualContentWidth
display.safeActualContentHeight

Overview

Returns four numbers corresponding to the top, left, bottom, and right "safe area" insets. The "safe area" is the rectangular region where it's safe to place important UI elements, ensuring that they are not obscured by status bars, device aspects like a sensor bar or rounded corners, software buttons, TV overscan areas, etc.

Essentially, these inset values represent the distance, in content units, between the corresponding screen edge and the imaginary boundary line where such elements will not interfere with or obscure screen content.

Syntax

display.getSafeAreaInsets()

Example

-- Gather insets (function returns these in the order of top, left, bottom, right)
local topInset, leftInset, bottomInset, rightInset = display.getSafeAreaInsets()

-- Create a vector rectangle sized exactly to the "safe area"
local safeArea = display.newRect(
    display.screenOriginX + leftInset, 
    display.screenOriginY + topInset, 
    display.actualContentWidth - ( leftInset + rightInset ), 
    display.actualContentHeight - ( topInset + bottomInset )
)
safeArea:translate( safeArea.width*0.5, safeArea.height*0.5 )