# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: ScreenGui type: class memory_category: Instances summary: | Primary container of on-screen 2D user interface elements. description: | `Class.ScreenGui` is a storage container for 2D `Class.GuiObject|GuiObjects` displayed on the user's screen. A `Class.ScreenGui` only shows if parented to a player's `Class.PlayerGui`; parenting a `Class.ScreenGui` to `Class.StarterGui` ensures it clones into each player's `Class.PlayerGui` when they join the experience and their character first spawns. See [On‑Screen UI Containers](../../../ui/on-screen-containers.md) for further details. Example ScreenGui with various GuiObject children, including a Frame, TextLabel, TextBox, and ImageButton. For performance improvements, the appearance of a `Class.ScreenGui` is cached until one of the following events occurs: - A descendant is added to or removed from it. - A property of a descendant changes. - A property of the `Class.ScreenGui` itself changes. If any of these events occur, the `Class.ScreenGui` appearance is recomputed on the next frame it gets rendered. code_samples: [] inherits: - LayerCollector descendants: - GuiMain tags: [] deprecation_message: '' properties: - name: ScreenGui.ClipToDeviceSafeArea summary: | Whether to clip the contents of this `Class.ScreenGui` to the device's safe area. description: | If this property is `true`, all `Class.GuiObject` descendants of the `Class.ScreenGui` will be clipped to the device's safe area (see `Enum.ScreenInsets`). The default is `true` to maintain backwards compatibility of UI that is intentionally hidden offscreen, such as objects that slide into view from a screen edge when they're needed. Mobile device showing UI button clipped by device safe area If this property is `false`, `Class.GuiObject` descendants will **not** be clipped to the device's safe area and may be obscured by the camera notch or other screen cutouts. Mobile device showing UI button overflowing device safe area, obscured by screen camera notch Note that this property will be ignored if you set `Class.ScreenGui.ScreenInsets|ScreenInsets` to `Enum.ScreenInsets|None`, as doing so implies that you intentionally want to disregard the device's safe insets. code_samples: [] type: boolean tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Appearance serialization: can_load: true can_save: true capabilities: - UI - name: ScreenGui.DisplayOrder summary: | Controls the Z-index order in which multiple `Class.ScreenGui` containers are drawn. description: | This property controls the Z-index order in which multiple `Class.ScreenGui` containers are drawn. Those with a higher `Class.ScreenGui.DisplayOrder|DisplayOrder` will be drawn on top of those with a lower value. code_samples: [] type: int tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: ScreenGui.IgnoreGuiInset summary: | Determines whether the `Class.ScreenGui` overflows into the range of Roblox's core UI elements. description: | If this property is `false` (default), `Class.ScreenGui.ScreenInsets|ScreenInsets` is set to `Enum.ScreenInsets|CoreUISafeInsets`, effectively keeping its bounds below the Roblox top bar core UI. If this property is changed to `true` and `Class.ScreenGui.ScreenInsets|ScreenInsets` is currently set to `Enum.ScreenInsets|CoreUISafeInsets`, `Class.ScreenGui.ScreenInsets|ScreenInsets` will be set to `Enum.ScreenInsets|DeviceSafeInsets`. See `Class.ScreenGui.ScreenInsets|ScreenInsets` for details on how screen insets affect the contents of a `Class.ScreenGui`. code_samples: [] type: boolean tags: - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: false capabilities: - UI - name: ScreenGui.SafeAreaCompatibility summary: | Specifies whether automatic UI compatibility transformations are applied to descendant "fullscreen" `Class.GuiObject|GuiObjects` on displays with screen cutouts. description: | This property specifies whether automatic UI compatibility transformations are applied to descendant "fullscreen" `Class.GuiObject|GuiObjects` of the `Class.ScreenGui` on displays with screen cutouts. Eligibility occurs if the total area of the descendant `Class.GuiObject` (including any applied border or `Class.UIStroke`) covers the device's safe area both horizontally and vertically. See the `Enum.SafeAreaCompatibility` enum reference for details. The default value is `Enum.SafeAreaCompatibility|FullscreenExtension` in order to automatically improve the appearance of UI that was authored for screens without any cutouts. However, it's recommended that you avoid fullscreen extensions for new work; instead, use the `Class.ScreenGui.ScreenInsets|ScreenInsets` property to specify which insets should be respected for different `Class.ScreenGui` containers. Note that descendant UI objects will continue to be clipped by the device's safe area if `Class.ScreenGui.ClipToDeviceSafeArea|ClipToDeviceSafeArea` is set to `true`. code_samples: [] type: SafeAreaCompatibility tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Appearance serialization: can_load: true can_save: true capabilities: - UI - name: ScreenGui.ScreenInsets summary: | Controls the safe area insets that are applied to the contents of the `Class.ScreenGui`. description: | This property controls the safe area insets that are applied to the contents of the `Class.ScreenGui`. The default of `Enum.ScreenInsets|CoreUISafeInsets` keeps all descendant `Class.GuiObject|GuiObjects` inside the core UI safe area, clear of the Roblox top bar buttons and other screen cutouts like the device's camera notch. Mobile device showing UI buttons inside core UI safe area If you set this property to `Enum.ScreenInsets|None`, UI objects may be obscured behind core UI objects or device cutouts like the camera notch. As a result, you should only use `Enum.ScreenInsets|None` for a `Class.ScreenGui` that contains noninteractive content like background images. See [On-Screen UI Containers](../../../ui/on-screen-containers.md#screen-insets) for alternative examples. code_samples: [] type: ScreenInsets tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Appearance serialization: can_load: true can_save: true capabilities: - UI methods: [] events: [] callbacks: []