Skip to main content

GuiHandler

This item only works when running on the client. Client

Gives each ScreenGui a handler that shows and hides it with a tween instead of a hard Enabled toggle. A handler owns a main container (the top-level frame of the gui) and an animation config that says what the container's properties should be when shown, what they should be when hidden, and which TweenInfo to use for each direction. By default the container tweens between the centre of the screen (UDim2.fromScale(0.5, 0.5)) and a position above the screen (UDim2.fromScale(0.5, -0.5)) over 0.25 seconds.

Show enables the gui and tweens the container to its shown properties; Hide tweens the container to its hidden properties and then disables the gui. Both accept an instant flag that sets the properties immediately instead of tweening, and both fire the Shown / Hidden / Toggled signals so other scripts can react. Every handler is registered in a module-level list, so ShowAll, HideAll, GetGuiHandler and WaitForGuiHandler let any client script work with guis it did not create.

GetOffScreenPosition computes a scale position just outside a given edge of the screen for a GuiObject, which makes it easy to build slide-in/slide-out configs with newAnimationConfig.

The module requires the client and errors when required on the server. It returns a table with the functions listed on this page plus new (the constructor), DefaultAnimationConfig, GuiHandlers and GuiHandlerAdded. 

local Players = game:GetService("Players")
local GuiHandler = require(path.to.GuiHandler)

local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local shopGui = playerGui:WaitForChild("Shop") :: ScreenGui
local shopFrame = shopGui:WaitForChild("Main") :: Frame

-- Slide the shop in from the right and hide it again by sliding out to the right
local config = GuiHandler.newAnimationConfig({
	ShowProperties = { Position = UDim2.fromScale(0.5, 0.5) },
	HideProperties = { Position = GuiHandler.GetOffScreenPosition(shopFrame, Vector2.new(1, 0)) },
	ShowTweenInfo = TweenInfo.new(0.3, Enum.EasingStyle.Back, Enum.EasingDirection.Out),
	HideTweenInfo = TweenInfo.new(0.2, Enum.EasingStyle.Quad, Enum.EasingDirection.In),
} :: any)

-- Start hidden; toggling ShopGui.Enabled from elsewhere will animate too
local shop = GuiHandler.new(shopGui, shopFrame, false, true, config)

shop.Toggled:Connect(function(isShowing)
	print("Shop is now", isShowing and "open" or "closed")
end)

local openButton = playerGui:WaitForChild("Hud"):WaitForChild("OpenShop") :: TextButton
openButton.Activated:Connect(function()
	if shop.IsShowing then
		shop:Hide()
	else
		shop:Show()
	end
end)

Credits: Trove and Signal are by sleitnick (sleitnick's RbxUtil). Wally installs both.

Installation and guide: GuiHandler package page.

Types​

GuiAnimationConfig​

</>
interface GuiAnimationConfig {
ShowProperties: {[string]: any}--

Property values applied to the main container when showing (tween target, or set directly when instant). Default { Position = UDim2.fromScale(0.5, 0.5) }.

HideProperties: {[string]: any}--

Property values applied to the main container when hiding. Default { Position = UDim2.fromScale(0.5, -0.5) }, just above the top of the screen.

ShowTweenInfo: TweenInfo--

TweenInfo used for the show tween. Default TweenInfo.new(0.25, Enum.EasingStyle.Quint, Enum.EasingDirection.InOut).

HideTweenInfo: TweenInfo--

TweenInfo used for the hide tween. Default TweenInfo.new(0.25, Enum.EasingStyle.Quint, Enum.EasingDirection.InOut).

}

Describes how a handler animates its main container. The property tables are passed straight to TweenService:Create, so any tweenable property of the container works (Position, Size, BackgroundTransparency, Rotation, ...). Build one with newAnimationConfig to fall back to the defaults for fields you leave out, or read DefaultAnimationConfig for the stock values.

Properties​

Gui​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.Gui: ScreenGui

The ScreenGui this handler manages. Show sets its Enabled to true before animating and Hide sets it to false after animating.

IsShowing​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.IsShowing: boolean

Whether the handler considers the gui shown. Initialised from Gui.Enabled in new, set to true at the start of Show and false at the start of Hide (before the tween plays). Show/Hide are no-ops when this already matches.

AnimationConfig​

</>
GuiHandler.AnimationConfig: GuiAnimationConfig

The config used by Animate. Defaults to DefaultAnimationConfig; replace it with SetAnimationConfig.

MainContainer​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.MainContainer: GuiObject?

The GuiObject that is tweened. new requires one, but if it is ever missing Animate warns and skips the animation (the gui is still enabled/disabled).

Trove​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.Trove: Trove

The Trove holding the handler's tweens and the Enabled listener. It is attached to Gui and MainContainer, so destroying either cleans it. Destroy cleans it as well.

Shown​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.Shown: Signal<>

Fires after Show has finished (after the show tween completes, or immediately when instant).

Hidden​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.Hidden: Signal<>

Fires after Hide has finished and the gui has been disabled.

Toggled​

This item is read only and cannot be modified. Read Only
</>
GuiHandler.Toggled: Signal<boolean>

Fires with true whenever Shown fires and false whenever Hidden fires, so you can watch both transitions with one connection.

DefaultAnimationConfig​

This item is read only and cannot be modified. Read OnlyModule
</>
GuiHandler.DefaultAnimationConfig: GuiAnimationConfig

Available on the module table (GuiHandler.DefaultAnimationConfig). The config used when new is given no AnimationConfig and the source of fallback values for newAnimationConfig: tween Position between UDim2.fromScale(0.5, 0.5) and UDim2.fromScale(0.5, -0.5) over 0.25 s with Quint/InOut easing. Do not mutate it; build your own with newAnimationConfig.

GuiHandlers​

This item is read only and cannot be modified. Read OnlyModule
</>
GuiHandler.GuiHandlers: {GuiHandler}

Available on the module table (GuiHandler.GuiHandlers). The live registry of every handler created with new and not yet destroyed, in creation order. Iterate it to inspect all guis; do not insert or remove entries yourself.

GuiHandlerAdded​

This item is read only and cannot be modified. Read OnlyModule
</>
GuiHandler.GuiHandlerAdded: Signal<GuiHandler>

Available on the module table (GuiHandler.GuiHandlerAdded). Fires with the new handler at the end of every new call. WaitForGuiHandler is built on it.

Functions​

ShowAll​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler.ShowAll(
instant: true?--

Skip the tweens and snap every gui to its shown state.

) → ()

Calls Show(instant) on every registered handler, one after another in registration order. Because an animated Show waits for its tween to finish, the guis appear sequentially and this function yields until the last one is done; pass instant = true to show everything at once without yielding.

HideAll​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler.HideAll(
instant: true?--

Skip the tweens and snap every gui to its hidden state.

) → ()

Calls Hide(instant) on every registered handler, one after another in registration order. Animated hides run sequentially and this function yields until the last tween completes; pass instant = true to hide everything immediately without yielding. Handy for cutscenes or a "hide HUD" setting.

WaitForGuiHandler​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler.WaitForGuiHandler(
gui: ScreenGui--

The gui whose handler you want.

) → GuiHandler--

The handler for gui.

Returns the handler registered for gui, yielding until one is created with new if it does not exist yet. Use this from scripts that run before the script that constructs the handler. There is no timeout: if no handler is ever created for that gui, the call never returns. 

local hud = GuiHandler.WaitForGuiHandler(playerGui:WaitForChild("Hud"))
hud:Hide()

GetGuiHandler​

</>
GuiHandler.GetGuiHandler(
gui: ScreenGui--

The gui to look up.

) → GuiHandler?--

The handler for gui, if one is registered.

Returns the handler registered for gui, or nil if none has been created (or it has been destroyed). Does not yield; use WaitForGuiHandler if the handler may not exist yet.

GetOffScreenPosition​

</>
GuiHandler.GetOffScreenPosition(
guiObject: GuiObject,--

The object to position; its Size, Position and AnchorPoint are read.

direction: Vector2,--

Which way to push the object off screen; normalised and rounded per axis.

offset: Vector2?--

Reserved for extra scale distance; currently unused.

) → UDim2--

Scale position just outside the chosen edge(s) of the screen.

Computes a UDim2 (scale only) that places guiObject fully outside the screen on the side given by direction, taking the object's Size scale and AnchorPoint into account. The direction is normalised and each axis rounded to -1, 0 or 1, so Vector2.new(-1, 0) means off the left edge, Vector2.new(0, 1) off the bottom, and Vector2.new(1, 1) off the bottom-right corner. An axis whose direction is 0 keeps the object's current position scale.

The result is meant to be used as the Position in a HideProperties (or ShowProperties) table for slide-in/slide-out animations. Only the Scale components of Size and Position are considered; pixel offsets are ignored. 

local offLeft = GuiHandler.GetOffScreenPosition(frame, Vector2.new(-1, 0))
NOTE

offset is validated but not applied in the current version; the returned position is the same with or without it.

Errors

TypeDescription
"Parameter passed is not a valid GuiObject"`guiObject` is not a `GuiObject`.
"direction must be a Vector2"`direction` is not a Vector2.
"offset must be a Vector2 or nil"`offset` is given but is not a Vector2.

newAnimationConfig​

</>
GuiHandler.newAnimationConfig(
config: GuiAnimationConfig--

Fields to override; missing fields use the defaults.

) → GuiAnimationConfig--

A new config with every field set.

Builds a complete GuiAnimationConfig from a partial one: every field that is nil in config is filled with the value from DefaultAnimationConfig. Returns a new table; the argument is not modified. Pass the result to new or SetAnimationConfig.

The parameter is typed as a full GuiAnimationConfig, so under --!strict you may need to cast a partial table ({ ... } :: any) when omitting fields. 

local config = GuiHandler.newAnimationConfig({
	HideProperties = { Position = UDim2.fromScale(0.5, 1.5) }, -- slide out the bottom
} :: any)

new​

</>
GuiHandler.new(
Gui: ScreenGui,--

The gui to manage.

MainContainer: GuiObject,--

The frame that is tweened; required despite being stored as optional.

ShowByDefault: boolean?,--

true to show instantly, false to hide instantly, nil to leave as is.

RunAutomatically: boolean?,--

Animate whenever Gui.Enabled changes externally.

AnimationConfig: GuiAnimationConfig?--

Animation config; defaults to DefaultAnimationConfig.

) → GuiHandler--

The registered handler.

Creates a handler for Gui, registers it so GetGuiHandler / WaitForGuiHandler / ShowAll / HideAll can find it, and fires GuiHandlerAdded. Exposed on the module as GuiHandler.new.

  • IsShowing starts as Gui.Enabled.
  • ShowByDefault: true calls Show(true) and false calls Hide(true) right away (both instant); nil leaves the gui as it is. Note that Show/Hide are no-ops when IsShowing already matches, so the container is only snapped into place when the state actually changes.
  • RunAutomatically: when true, changing Gui.Enabled from anywhere (another script, the Studio explorer) triggers an animated Show/Hide to match. This lets you drive the gui with the plain Enabled property and still get tweens.
  • The handler's Trove is attached to both Gui and MainContainer, so destroying either cleans up the tweens and listener. Call Destroy to also remove the handler from the registry.

Errors

TypeDescription
"Invalid gui parameter, must be ScreenGui"`Gui` is not a `ScreenGui`.
"Invalid MainContainer parameter, must be GuiObject"`MainContainer` is not a `GuiObject`.

SetAnimationConfig​

</>
GuiHandler:SetAnimationConfig(
newConfig: GuiAnimationConfig--

The config to use from now on.

) → ()

Replaces the handler's AnimationConfig. Takes effect on the next Show/Hide; a tween that is already playing is not affected. Use newAnimationConfig to build a config that falls back to the defaults.

Animate​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler:Animate(
showing: boolean,--

true to apply ShowProperties, false to apply HideProperties.

instant: true?--

Set the properties immediately instead of tweening.

) → ()

Applies the shown or hidden properties to MainContainer. Show and Hide call this for you; call it directly only when you want to replay the animation without changing IsShowing or Gui.Enabled.

  • Does nothing while Gui.Enabled is false (a disabled gui cannot be animated).
  • Warns and does nothing if there is no MainContainer or no AnimationConfig.
  • With instant, each property in ShowProperties/HideProperties is assigned directly (a failed assignment is warned about, not raised).
  • Otherwise a tween is created with the matching TweenInfo, added to the Trove, played, and this method yields until the tween completes.

Show​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler:Show(
instant: true?--

Snap to the shown properties instead of tweening.

) → ()

Shows the gui: sets IsShowing to true, enables Gui, runs Animate(true, instant) to move the container to its shown properties, then fires Shown (and therefore Toggled(true)). Does nothing if IsShowing is already true.

When not instant this yields for the duration of ShowTweenInfo before Shown fires.

Hide​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
GuiHandler:Hide(
instant: true?--

Snap to the hidden properties instead of tweening.

) → ()

Hides the gui: sets IsShowing to false, runs Animate(false, instant) to move the container to its hidden properties, disables Gui once that is done, then fires Hidden (and therefore Toggled(false)). Does nothing if IsShowing is already false.

When not instant this yields for the duration of HideTweenInfo before the gui is disabled and Hidden fires.

Destroy​

</>
GuiHandler:Destroy() → ()

Unregisters the handler (so GetGuiHandler, ShowAll and HideAll no longer see it) and cleans its Trove, cancelling in-flight tweens and disconnecting the RunAutomatically listener. The ScreenGui itself is not destroyed or hidden, and the handler's signals are not destroyed.

Show raw api
{
    "functions": [
        {
            "name": "ShowAll",
            "desc": "Calls `Show(instant)` on every registered handler, one after another in registration order.\nBecause an animated `Show` waits for its tween to finish, the guis appear sequentially and this\nfunction yields until the last one is done; pass `instant = true` to show everything at once\nwithout yielding.",
            "params": [
                {
                    "name": "instant",
                    "desc": "Skip the tweens and snap every gui to its shown state.",
                    "lua_type": "true?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 198,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "HideAll",
            "desc": "Calls `Hide(instant)` on every registered handler, one after another in registration order.\nAnimated hides run sequentially and this function yields until the last tween completes; pass\n`instant = true` to hide everything immediately without yielding. Handy for cutscenes or a\n\"hide HUD\" setting.",
            "params": [
                {
                    "name": "instant",
                    "desc": "Skip the tweens and snap every gui to its hidden state.",
                    "lua_type": "true?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 218,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "WaitForGuiHandler",
            "desc": "Returns the handler registered for `gui`, yielding until one is created with `new` if it does\nnot exist yet. Use this from scripts that run before the script that constructs the handler.\nThere is no timeout: if no handler is ever created for that gui, the call never returns.\n\n```lua\nlocal hud = GuiHandler.WaitForGuiHandler(playerGui:WaitForChild(\"Hud\"))\nhud:Hide()\n```",
            "params": [
                {
                    "name": "gui",
                    "desc": "The gui whose handler you want.",
                    "lua_type": "ScreenGui"
                }
            ],
            "returns": [
                {
                    "desc": "The handler for `gui`.",
                    "lua_type": "GuiHandler"
                }
            ],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 243,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "GetGuiHandler",
            "desc": "Returns the handler registered for `gui`, or `nil` if none has been created (or it has been\ndestroyed). Does not yield; use `WaitForGuiHandler` if the handler may not exist yet.",
            "params": [
                {
                    "name": "gui",
                    "desc": "The gui to look up.",
                    "lua_type": "ScreenGui"
                }
            ],
            "returns": [
                {
                    "desc": "The handler for `gui`, if one is registered.",
                    "lua_type": "GuiHandler?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 270,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "GetOffScreenPosition",
            "desc": "Computes a `UDim2` (scale only) that places `guiObject` fully outside the screen on the side\ngiven by `direction`, taking the object's `Size` scale and `AnchorPoint` into account. The\ndirection is normalised and each axis rounded to -1, 0 or 1, so `Vector2.new(-1, 0)` means off\nthe left edge, `Vector2.new(0, 1)` off the bottom, and `Vector2.new(1, 1)` off the bottom-right\ncorner. An axis whose direction is 0 keeps the object's current position scale.\n\nThe result is meant to be used as the `Position` in a `HideProperties` (or `ShowProperties`)\ntable for slide-in/slide-out animations. Only the `Scale` components of `Size` and `Position`\nare considered; pixel offsets are ignored.\n\n```lua\nlocal offLeft = GuiHandler.GetOffScreenPosition(frame, Vector2.new(-1, 0))\n```\n\n:::note\n`offset` is validated but not applied in the current version; the returned position is the same\nwith or without it.\n:::",
            "params": [
                {
                    "name": "guiObject",
                    "desc": "The object to position; its `Size`, `Position` and `AnchorPoint` are read.",
                    "lua_type": "GuiObject"
                },
                {
                    "name": "direction",
                    "desc": "Which way to push the object off screen; normalised and rounded per axis.",
                    "lua_type": "Vector2"
                },
                {
                    "name": "offset",
                    "desc": "Reserved for extra scale distance; currently unused.",
                    "lua_type": "Vector2?"
                }
            ],
            "returns": [
                {
                    "desc": "Scale position just outside the chosen edge(s) of the screen.",
                    "lua_type": "UDim2"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Parameter passed is not a valid GuiObject\"",
                    "desc": "`guiObject` is not a `GuiObject`."
                },
                {
                    "lua_type": "\"direction must be a Vector2\"",
                    "desc": "`direction` is not a Vector2."
                },
                {
                    "lua_type": "\"offset must be a Vector2 or nil\"",
                    "desc": "`offset` is given but is not a Vector2."
                }
            ],
            "source": {
                "line": 313,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "newAnimationConfig",
            "desc": "Builds a complete `GuiAnimationConfig` from a partial one: every field that is `nil` in\n`config` is filled with the value from `DefaultAnimationConfig`. Returns a new table; the\nargument is not modified. Pass the result to `new` or `SetAnimationConfig`.\n\nThe parameter is typed as a full `GuiAnimationConfig`, so under `--!strict` you may need to\ncast a partial table (`{ ... } :: any`) when omitting fields.\n\n```lua\nlocal config = GuiHandler.newAnimationConfig({\n\tHideProperties = { Position = UDim2.fromScale(0.5, 1.5) }, -- slide out the bottom\n} :: any)\n```",
            "params": [
                {
                    "name": "config",
                    "desc": "Fields to override; missing fields use the defaults.",
                    "lua_type": "GuiAnimationConfig"
                }
            ],
            "returns": [
                {
                    "desc": "A new config with every field set.",
                    "lua_type": "GuiAnimationConfig"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 373,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "new",
            "desc": "Creates a handler for `Gui`, registers it so `GetGuiHandler` / `WaitForGuiHandler` / `ShowAll`\n/ `HideAll` can find it, and fires `GuiHandlerAdded`. Exposed on the module as\n`GuiHandler.new`.\n\n- `IsShowing` starts as `Gui.Enabled`.\n- `ShowByDefault`: `true` calls `Show(true)` and `false` calls `Hide(true)` right away (both\n  instant); `nil` leaves the gui as it is. Note that `Show`/`Hide` are no-ops when `IsShowing`\n  already matches, so the container is only snapped into place when the state actually changes.\n- `RunAutomatically`: when `true`, changing `Gui.Enabled` from anywhere (another script, the\n  Studio explorer) triggers an animated `Show`/`Hide` to match. This lets you drive the gui with\n  the plain `Enabled` property and still get tweens.\n- The handler's Trove is attached to both `Gui` and `MainContainer`, so destroying either\n  cleans up the tweens and listener. Call `Destroy` to also remove the handler from the\n  registry.",
            "params": [
                {
                    "name": "Gui",
                    "desc": "The gui to manage.",
                    "lua_type": "ScreenGui"
                },
                {
                    "name": "MainContainer",
                    "desc": "The frame that is tweened; required despite being stored as optional.",
                    "lua_type": "GuiObject"
                },
                {
                    "name": "ShowByDefault",
                    "desc": "`true` to show instantly, `false` to hide instantly, `nil` to leave as is.",
                    "lua_type": "boolean?"
                },
                {
                    "name": "RunAutomatically",
                    "desc": "Animate whenever `Gui.Enabled` changes externally.",
                    "lua_type": "boolean?"
                },
                {
                    "name": "AnimationConfig",
                    "desc": "Animation config; defaults to `DefaultAnimationConfig`.",
                    "lua_type": "GuiAnimationConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "The registered handler.",
                    "lua_type": "GuiHandler"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"Invalid gui parameter, must be ScreenGui\"",
                    "desc": "`Gui` is not a `ScreenGui`."
                },
                {
                    "lua_type": "\"Invalid MainContainer parameter, must be GuiObject\"",
                    "desc": "`MainContainer` is not a `GuiObject`."
                }
            ],
            "source": {
                "line": 411,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "SetAnimationConfig",
            "desc": "Replaces the handler's `AnimationConfig`. Takes effect on the next `Show`/`Hide`; a tween that is\nalready playing is not affected. Use `newAnimationConfig` to build a config that falls back to\nthe defaults.",
            "params": [
                {
                    "name": "newConfig",
                    "desc": "The config to use from now on.",
                    "lua_type": "GuiAnimationConfig"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 487,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Animate",
            "desc": "Applies the shown or hidden properties to `MainContainer`. `Show` and `Hide` call this for you;\ncall it directly only when you want to replay the animation without changing `IsShowing` or\n`Gui.Enabled`.\n\n- Does nothing while `Gui.Enabled` is `false` (a disabled gui cannot be animated).\n- Warns and does nothing if there is no `MainContainer` or no `AnimationConfig`.\n- With `instant`, each property in `ShowProperties`/`HideProperties` is assigned directly (a\n  failed assignment is warned about, not raised).\n- Otherwise a tween is created with the matching `TweenInfo`, added to the Trove, played, and\n  this method **yields until the tween completes**.",
            "params": [
                {
                    "name": "showing",
                    "desc": "`true` to apply `ShowProperties`, `false` to apply `HideProperties`.",
                    "lua_type": "boolean"
                },
                {
                    "name": "instant",
                    "desc": "Set the properties immediately instead of tweening.",
                    "lua_type": "true?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 509,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Show",
            "desc": "Shows the gui: sets `IsShowing` to `true`, enables `Gui`, runs `Animate(true, instant)` to move\nthe container to its shown properties, then fires `Shown` (and therefore `Toggled(true)`).\nDoes nothing if `IsShowing` is already `true`.\n\nWhen not instant this yields for the duration of `ShowTweenInfo` before `Shown` fires.",
            "params": [
                {
                    "name": "instant",
                    "desc": "Snap to the shown properties instead of tweening.",
                    "lua_type": "true?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 578,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Hide",
            "desc": "Hides the gui: sets `IsShowing` to `false`, runs `Animate(false, instant)` to move the container\nto its hidden properties, disables `Gui` once that is done, then fires `Hidden` (and therefore\n`Toggled(false)`). Does nothing if `IsShowing` is already `false`.\n\nWhen not instant this yields for the duration of `HideTweenInfo` before the gui is disabled and\n`Hidden` fires.",
            "params": [
                {
                    "name": "instant",
                    "desc": "Snap to the hidden properties instead of tweening.",
                    "lua_type": "true?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 611,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Unregisters the handler (so `GetGuiHandler`, `ShowAll` and `HideAll` no longer see it) and\ncleans its Trove, cancelling in-flight tweens and disconnecting the `RunAutomatically`\nlistener. The `ScreenGui` itself is not destroyed or hidden, and the handler's signals are not\ndestroyed.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 640,
                "path": "packages/src/GuiHandler/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Gui",
            "desc": "The `ScreenGui` this handler manages. `Show` sets its `Enabled` to `true` before animating and\n`Hide` sets it to `false` after animating.",
            "lua_type": "ScreenGui",
            "readonly": true,
            "source": {
                "line": 111,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "IsShowing",
            "desc": "Whether the handler considers the gui shown. Initialised from `Gui.Enabled` in `new`, set to\n`true` at the start of `Show` and `false` at the start of `Hide` (before the tween plays).\n`Show`/`Hide` are no-ops when this already matches.",
            "lua_type": "boolean",
            "readonly": true,
            "source": {
                "line": 120,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "AnimationConfig",
            "desc": "The config used by `Animate`. Defaults to `DefaultAnimationConfig`; replace it with\n`SetAnimationConfig`.",
            "lua_type": "GuiAnimationConfig",
            "source": {
                "line": 127,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "MainContainer",
            "desc": "The `GuiObject` that is tweened. `new` requires one, but if it is ever missing `Animate` warns\nand skips the animation (the gui is still enabled/disabled).",
            "lua_type": "GuiObject?",
            "readonly": true,
            "source": {
                "line": 135,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Trove",
            "desc": "The [Trove](https://sleitnick.github.io/RbxUtil/api/Trove/) holding the handler's tweens and the\n`Enabled` listener. It is attached to `Gui` and `MainContainer`, so destroying either cleans it.\n`Destroy` cleans it as well.",
            "lua_type": "Trove",
            "readonly": true,
            "source": {
                "line": 144,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Shown",
            "desc": "Fires after `Show` has finished (after the show tween completes, or immediately when instant).",
            "lua_type": "Signal<>",
            "readonly": true,
            "source": {
                "line": 151,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Hidden",
            "desc": "Fires after `Hide` has finished and the gui has been disabled.",
            "lua_type": "Signal<>",
            "readonly": true,
            "source": {
                "line": 158,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "Toggled",
            "desc": "Fires with `true` whenever `Shown` fires and `false` whenever `Hidden` fires, so you can watch\nboth transitions with one connection.",
            "lua_type": "Signal<boolean>",
            "readonly": true,
            "source": {
                "line": 166,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "DefaultAnimationConfig",
            "desc": "Available on the module table (`GuiHandler.DefaultAnimationConfig`). The config used when `new`\nis given no `AnimationConfig` and the source of fallback values for `newAnimationConfig`: tween\n`Position` between `UDim2.fromScale(0.5, 0.5)` and `UDim2.fromScale(0.5, -0.5)` over 0.25 s with\n`Quint`/`InOut` easing. Do not mutate it; build your own with `newAnimationConfig`.",
            "lua_type": "GuiAnimationConfig",
            "tags": [
                "Module"
            ],
            "readonly": true,
            "source": {
                "line": 664,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "GuiHandlers",
            "desc": "Available on the module table (`GuiHandler.GuiHandlers`). The live registry of every handler\ncreated with `new` and not yet destroyed, in creation order. Iterate it to inspect all guis; do\nnot insert or remove entries yourself.",
            "lua_type": "{ GuiHandler }",
            "tags": [
                "Module"
            ],
            "readonly": true,
            "source": {
                "line": 675,
                "path": "packages/src/GuiHandler/init.luau"
            }
        },
        {
            "name": "GuiHandlerAdded",
            "desc": "Available on the module table (`GuiHandler.GuiHandlerAdded`). Fires with the new handler at the\nend of every `new` call. `WaitForGuiHandler` is built on it.",
            "lua_type": "Signal<GuiHandler>",
            "tags": [
                "Module"
            ],
            "readonly": true,
            "source": {
                "line": 685,
                "path": "packages/src/GuiHandler/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "GuiAnimationConfig",
            "desc": "Describes how a handler animates its main container. The property tables are passed straight\nto `TweenService:Create`, so any tweenable property of the container works (`Position`, `Size`,\n`BackgroundTransparency`, `Rotation`, ...). Build one with `newAnimationConfig` to fall back to\nthe defaults for fields you leave out, or read `DefaultAnimationConfig` for the stock values.",
            "fields": [
                {
                    "name": "ShowProperties",
                    "lua_type": "{ [string]: any }",
                    "desc": "Property values applied to the main container when showing (tween target, or set directly when instant). Default `{ Position = UDim2.fromScale(0.5, 0.5) }`."
                },
                {
                    "name": "HideProperties",
                    "lua_type": "{ [string]: any }",
                    "desc": "Property values applied to the main container when hiding. Default `{ Position = UDim2.fromScale(0.5, -0.5) }`, just above the top of the screen."
                },
                {
                    "name": "ShowTweenInfo",
                    "lua_type": "TweenInfo",
                    "desc": "`TweenInfo` used for the show tween. Default `TweenInfo.new(0.25, Enum.EasingStyle.Quint, Enum.EasingDirection.InOut)`."
                },
                {
                    "name": "HideTweenInfo",
                    "lua_type": "TweenInfo",
                    "desc": "`TweenInfo` used for the hide tween. Default `TweenInfo.new(0.25, Enum.EasingStyle.Quint, Enum.EasingDirection.InOut)`."
                }
            ],
            "source": {
                "line": 102,
                "path": "packages/src/GuiHandler/init.luau"
            }
        }
    ],
    "name": "GuiHandler",
    "desc": "Gives each `ScreenGui` a handler that shows and hides it with a tween instead of a hard\n`Enabled` toggle. A handler owns a **main container** (the top-level frame of the gui) and an\nanimation config that says what the container's properties should be when shown, what they\nshould be when hidden, and which `TweenInfo` to use for each direction. By default the\ncontainer tweens between the centre of the screen (`UDim2.fromScale(0.5, 0.5)`) and a position\nabove the screen (`UDim2.fromScale(0.5, -0.5)`) over 0.25 seconds.\n\n`Show` enables the gui and tweens the container to its shown properties; `Hide` tweens the\ncontainer to its hidden properties and then disables the gui. Both accept an `instant` flag\nthat sets the properties immediately instead of tweening, and both fire the `Shown` / `Hidden`\n/ `Toggled` signals so other scripts can react. Every handler is registered in a module-level\nlist, so `ShowAll`, `HideAll`, `GetGuiHandler` and `WaitForGuiHandler` let any client script\nwork with guis it did not create.\n\n`GetOffScreenPosition` computes a scale position just outside a given edge of the screen for a\n`GuiObject`, which makes it easy to build slide-in/slide-out configs with\n`newAnimationConfig`.\n\nThe module requires the client and errors when required on the server. It returns a table with\nthe functions listed on this page plus `new` (the constructor), `DefaultAnimationConfig`,\n`GuiHandlers` and `GuiHandlerAdded`.\n\n```lua\nlocal Players = game:GetService(\"Players\")\nlocal GuiHandler = require(path.to.GuiHandler)\n\nlocal playerGui = Players.LocalPlayer:WaitForChild(\"PlayerGui\")\nlocal shopGui = playerGui:WaitForChild(\"Shop\") :: ScreenGui\nlocal shopFrame = shopGui:WaitForChild(\"Main\") :: Frame\n\n-- Slide the shop in from the right and hide it again by sliding out to the right\nlocal config = GuiHandler.newAnimationConfig({\n\tShowProperties = { Position = UDim2.fromScale(0.5, 0.5) },\n\tHideProperties = { Position = GuiHandler.GetOffScreenPosition(shopFrame, Vector2.new(1, 0)) },\n\tShowTweenInfo = TweenInfo.new(0.3, Enum.EasingStyle.Back, Enum.EasingDirection.Out),\n\tHideTweenInfo = TweenInfo.new(0.2, Enum.EasingStyle.Quad, Enum.EasingDirection.In),\n} :: any)\n\n-- Start hidden; toggling ShopGui.Enabled from elsewhere will animate too\nlocal shop = GuiHandler.new(shopGui, shopFrame, false, true, config)\n\nshop.Toggled:Connect(function(isShowing)\n\tprint(\"Shop is now\", isShowing and \"open\" or \"closed\")\nend)\n\nlocal openButton = playerGui:WaitForChild(\"Hud\"):WaitForChild(\"OpenShop\") :: TextButton\nopenButton.Activated:Connect(function()\n\tif shop.IsShowing then\n\t\tshop:Hide()\n\telse\n\t\tshop:Show()\n\tend\nend)\n```\n\n**Credits:** [Trove](https://sleitnick.github.io/RbxUtil/api/Trove/) and [Signal](https://sleitnick.github.io/RbxUtil/api/Signal/) are by [sleitnick](https://github.com/Sleitnick) ([sleitnick's RbxUtil](https://sleitnick.github.io/RbxUtil/)). Wally installs both.\n\nInstallation and guide: [GuiHandler package page](/docs/packages/gui-handler).",
    "realm": [
        "Client"
    ],
    "source": {
        "line": 79,
        "path": "packages/src/GuiHandler/init.luau"
    }
}