> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/development/api-reference/classes/screengui.md).

# ScreenGui

ScreenGui : `LayerCollector`

## Overview

ScreenGui is a container holding 2D UI elements (GuiObject) displayed on user screen. For these elements to be actually displayed, ScreenGui must be placed in player’s PlayerGui. If it is placed in StarterGui, it is automatically replicated to each player’s PlayerGui when a player enters the game and a character is created for the first time.

ScreenGui may contain a variety of child UI elements such as Frame, TextLabel, and ImageButton.

In addition, ScreenGui internally caches rendering results and reuse them when there are no changes to optimize performance. However, if the properties of ScreenGui itself are changed, the properties of child elements are changed, or child elements are added or removed, the screen information is recalculated in the next rendering frame.

ScreenGui **can be controlled only in client environment**.

## Properties

### ClipToDeviceSafeArea

`boolean`

Specifies whether to clip descendant UI elements that extend outside the safe area set by ScreenInsets.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ClipToDeviceSafeArea = true
```

### DisplayOrder

`number`

Defines the overlapping order when multiple ScreenGuis are simultaneously displayed on screen. A ScreenGui with a higher DisplayOrder value is placed forward than a ScreenGui with a lower DisplayOrder, so it can visually form a more forward layer.

You can enter an integer value between 0 and 999,999,999. The default value is 0. Higher values are displayed above ScreenGuis with lower values.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.DisplayOrder = 2
```

### IgnoreGuiInset

`boolean`

Specifies whether to ignore the system UI area and place descendant UI elements based on the entire screen.

It is linked with ScreenInsets. If set to false, ScreenInsets changes to CoreUISafeInsets, and if ScreenInsets is set to a value other than CoreUISafeInsets, this property becomes true.

Using ScreenInsets is recommended for newly written scripts.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.IgnoreGuiInset = false
```

### ResetOnSpawn

`boolean`

Specifies whether to recreate this ScreenGui in its initial state when the player's character respawns.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ResetOnSpawn = false
```

### SafeAreaCompatibility

`Enum.SafeAreaCompatibility`

Specifies whether to extend the background to the edges of the screen when UI made to fill the entire screen is placed inside the safe area.

* `None`: Does not extend.
* `FullscreenExtension`: When ScreenInsets is not None, extends a background the size of the entire screen to the edges of the screen.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ScreenInsets = Enum.ScreenInsets.DeviceSafeInsets
ScreenGui.SafeAreaCompatibility = Enum.SafeAreaCompatibility.FullscreenExtension
```

### ScreenInsets

`Enum.ScreenInsets`

Specifies the screen safe area used as the reference when placing descendant UI elements.

* `None`: Uses the entire screen without applying a safe area.
* `DeviceSafeInsets`: Uses the area excluding the device's display-restricted areas, such as a notch.
* `CoreUISafeInsets`: Uses the area excluding the device's display-restricted areas and the system UI area.
* `TopbarSafeInsets`: Uses a safe area that takes the top bar area into account.

Placing elements that must be visible, such as buttons and text, inside the safe area is recommended.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.ScreenInsets = Enum.ScreenInsets.DeviceSafeInsets
```

### TabKeyboardNavigation

`boolean`

Specifies whether the buttons in this ScreenGui can receive keyboard focus.

#### Code Samples

```lua
local ScreenGui = script.Parent

ScreenGui.TabKeyboardNavigation = true
```

## Methods

### GetGuiObjectsAtPosition

A method that finds all descendant UI elements of this ScreenGui at the specified screen coordinates and returns them as an array.

Elements are returned in order starting from those displayed in front, and elements covered by other elements are also included. Elements whose IsNotOccluded is false and elements at positions that are clipped and not visible are excluded.

#### Parameters

| `number` x | The X coordinate (in pixels) on screen. |
| ---------- | --------------------------------------- |
| `number` y | The Y coordinate (in pixels) on screen. |

#### Return

| `Array` | An array of GuiObjects at the coordinates. |
| ------- | ------------------------------------------ |

#### Code Samples

```lua
local ScreenGui = script.Parent

local PositionX = 150
local PositionY = 200
local GuiObjects = ScreenGui:GetGuiObjectsAtPosition(PositionX, PositionY)
for _, guiObject in ipairs(GuiObjects) do
    print(guiObject.Name)
end
```

## Events

## See also

{% content-ref url="/pages/Hgp8bh8C44modKPwUBkg" %}
[GUI](/manual/studio-manual/gui.md)
{% endcontent-ref %}