Reference API Roblox

Engine API

Website

Related

Reference API Roblox

ScreenGui

Primary container of on-screen 2D user interface elements.

Member index 6

HistoryMember
602ClipToDeviceSafeArea: bool
553DisplayOrder: int
554IgnoreGuiInset: bool
602SafeAreaCompatibility: SafeAreaCompatibility
631ScreenInsets: ScreenInsets
inherited from LayerCollector
553Enabled: bool
553ResetOnSpawn: bool
553ZIndexBehavior: ZIndexBehavior
622GetGuiObjectsAtPosition(x: int, y: int): Objects
462GetLayoutNodeTree(): Dictionary
inherited from GuiBase2d
553AbsolutePosition: Vector2
553AbsoluteRotation: float
553AbsoluteSize: Vector2
553AutoLocalize: bool
553RootLocalizationTable: LocalizationTable
553SelectionBehaviorDown: SelectionBehavior
553SelectionBehaviorLeft: SelectionBehavior
553SelectionBehaviorRight: SelectionBehavior
553SelectionBehaviorUp: SelectionBehavior
553SelectionGroup: bool
525SelectionChanged(amISelected: bool, previousSelection: GuiObject, newSelection: GuiObject)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553ClassName: string
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
553className: string
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
486GetChildren(): Objects
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
462GetPropertyChangedSignal(property: string): RBXScriptSignal
641GetStyled(name: string): Variant
576GetTags(): Array
576HasTag(tag: string): bool
486IsA(className: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
553children(): Objects
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
553getChildren(): Objects
462isA(className: string): bool
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462Changed(property: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
553childAdded(child: Instance)

Removed member index 2

HistoryMember
310Enabled: bool
329ResetOnSpawn: bool

Description

The main storage object for 2D GuiObjects displayed on the user's screen. A ScreenGui only shows if parented to a player's PlayerGui; parenting a ScreenGui to StarterGui ensures it clones into each player's PlayerGui when they join the experience and their character first spawns. See On‑Screen UI Containers for further details.

Example ScreenGui with various GuiObject children, including a Frame, TextLabel, TextBox, and ImageButton.

For performance improvements, the appearance of a 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 ScreenGui itself changes.

If any of these events occur, the ScreenGui appearance is recomputed on the next frame it gets rendered.

History 34

Members 6

ClipToDeviceSafeArea

TypeDefault
booltrue

If this property is true, all GuiObject descendants of this ScreenGui will be clipped to the device's safe area (see 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, 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 ScreenGui.ScreenInsets to None, as doing so implies that you intentionally want to disregard the device's safe insets.

History 5

DisplayOrder

TypeDefault
int0

This property controls the Z-index order in which multiple ScreenGuis are drawn. ScreenGuis with a higher DisplayOrder will be drawn on top of those with a lower value.

History 4

IgnoreGuiInset

TypeDefault
boolfalse

If this property is false (default), ScreenInsets is set to CoreUISafeInsets, effectively keeping its bounds below the Roblox top bar core UI.

If this property is changed to true and ScreenInsets is currently set to CoreUISafeInsets, ScreenInsets will be set to DeviceSafeInsets.

See ScreenInsets for details on how screen insets affect the contents of a ScreenGui.

History 5

SafeAreaCompatibility

TypeDefault
SafeAreaCompatibilityFullscreenExtension

This property specifies whether automatic UI compatibility transformations are applied to descendant "fullscreen" GuiObjects of this ScreenGui on displays with screen cutouts. Eligibility occurs if the total area of the descendant GuiObject (including any applied border or UIStroke) covers the device's safe area both horizontally and vertically. See the SafeAreaCompatibility enum reference for details.

The default value is 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 ScreenInsets property to specify which insets should be respected for different ScreenGuis.

Note that descendant UI objects will continue to be clipped by the device's safe area if ClipToDeviceSafeArea is set to true.

History 5

ScreenInsets

TypeDefault
ScreenInsetsCoreUISafeInsets

This property controls the safe area insets that are applied to the contents of this ScreenGui.

The default of CoreUISafeInsets keeps all descendant 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 None, UI objects may be obscured behind core UI objects or device cutouts like the camera notch. As a result, you should only use None for a ScreenGui that contains noninteractive content like background images.

See On-Screen UI Containers for alternative examples.

History 3

Removed members 2

Enabled

TypeDefault
bool

History 2

ResetOnSpawn

TypeDefault
bool

History 2

Settings