TooltipCreator — A lightweight tooltip utility for Roblox UI

TooltipCreator, a lightweight, standalone tooltip utility for Roblox interfaces.

TooltipCreator lets you register any GuiObject—such as a button, frame, or image—and automatically display a configurable text tooltip while the user's mouse is hovering over it.

The module handles tooltip creation, cursor tracking, viewport-aware positioning, delayed display, dynamic text, and cleanup internally, while keeping the public API small and simple.

Quick example

TooltipCreator attaches to any GuiObject through Register.

local TooltipCreator = require(ReplicatedStorage.TooltipCreator)

local Tooltips = TooltipCreator.new()

Tooltips:Register(script.Parent.PlayButton, "Start playing the game.")

The tooltip appears automatically while the mouse hovers over PlayButton and disappears when the mouse leaves. Everything else—positioning, delay, and cleanup—is handled internally.

🚀 Features

Hover-based tooltips

Register a tooltip on any GuiObject and TooltipCreator handles the rest.

Tooltips:Register(script.Parent.PlayButton, "Start playing the game.")

Tooltips appear on MouseEnter and disappear on MouseLeave, with an optional delay before showing.

Dynamic tooltips

Tooltip text may also be provided through a callback. The callback is evaluated whenever the tooltip is about to be displayed, making it useful for values that may change over time.

Tooltips:Register(script.Parent.CoinsButton, function()
	local coins = player:GetAttribute("Coins") or 0

	return `You currently have {coins} coins.`
end)

Returning nil or an empty string from the callback prevents the tooltip from being shown.

Viewport-aware positioning

Tooltips follow the cursor and automatically flip and clamp themselves inside the viewport. TooltipCreator first attempts to place the tooltip below and to the right of the cursor, then flips to the opposite side when there is insufficient space.

Configurable appearance

Each registered tooltip may override text, color, sizing, and layout independently of the global defaults.

Tooltips:Register(script.Parent.SettingsButton, "Open the settings menu.", {
	TextSize = 16,
	BackgroundColor3 = Color3.fromRGB(30, 30, 34),
	CornerRadius = UDim.new(0, 6),
})

Efficient by design

TooltipCreator reuses a single tooltip instance across all registrations instead of creating new UI for every hover, and automatically unregisters elements once they're destroyed.

Fully typed, no dependencies

The module ships with a fully typed Luau API and has no external dependencies or framework requirements.

📖 Basic usage

Place the TooltipCreator ModuleScript somewhere accessible to your client scripts, such as ReplicatedStorage. TooltipCreator must be required and used from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local TooltipCreator = require(ReplicatedStorage.TooltipCreator)

local Tooltips = TooltipCreator.new()

Tooltips:Register(
	script.Parent.PlayButton,
	"Start playing the game."
)

Example: dynamic coin counter tooltip

Tooltips:Register(script.Parent.CoinsButton, function()
	local coins = player:GetAttribute("Coins") or 0

	return `You currently have {coins} coins.`
end, {
	MaxWidth = 260,
	BackgroundColor3 = Color3.fromRGB(35, 35, 40),
})

Example: conditionally hidden tooltip

Tooltips:Register(script.Parent.LockedButton, function()
	if player:GetAttribute("HasUnlockedFeature") then
		return nil
	end

	return "Complete the tutorial to unlock this feature."
end, {
	TextColor3 = Color3.fromRGB(255, 220, 120),
})

Example: custom global configuration

local Tooltips = TooltipCreator.new({
	Name = "GameTooltips",
	DisplayOrder = 1000,
	EdgePadding = 6,
	DefaultShowDelay = 0.15,
})

⚙️ API

TooltipCreator.new(config?)

Creates a new TooltipCreator instance. An optional configuration table may be provided to customize global behavior.

local Tooltips = TooltipCreator.new()

Tooltips:Register(trigger, text, options?)

Registers or updates a tooltip for a GuiObject.

Tooltips:Register(Button, "Tooltip text")

text may be either a string or a callback returning a string or nil. Registering the same object again updates its existing text and options without creating duplicate event connections.

Tooltips:Unregister(trigger)

Removes a previously registered tooltip and disconnects its associated events.

Tooltips:Unregister(Button)

Registered elements are also automatically unregistered when they are destroyed.

Tooltips:SetEnabled(enabled)

Globally enables or disables tooltip display.

Tooltips:SetEnabled(false)

Disabling tooltips immediately hides the active tooltip. Registered tooltips remain stored and can be restored by enabling the instance again.

Tooltips:IsEnabled()

Returns whether tooltip display is currently enabled.

local enabled = Tooltips:IsEnabled()

Tooltips:Clear()

Immediately hides the currently visible tooltip, without removing any registered tooltips.

Tooltips:Clear()

Tooltips:Destroy()

Completely destroys the TooltipCreator instance.

Tooltips:Destroy()

This hides the active tooltip, cancels pending tooltip requests, disconnects every registered UI element, stops cursor tracking, and destroys the generated tooltip interface. The instance must not be used after calling Destroy().

Complete options reference

You normally only need to provide the options you want to change. Any omitted options use the module defaults.

Tooltip options

Passed per-registration as the third argument to Register.

Constructor configuration

Passed to TooltipCreator.new() to configure global behavior.

Complete example

local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local TooltipCreator = require(ReplicatedStorage.TooltipCreator)

local player = Players.LocalPlayer
local interface = script.Parent

local Tooltips = TooltipCreator.new({
	DefaultShowDelay = 0.15,
	DisplayOrder = 1000,
})

Tooltips:Register(interface.PlayButton, "Start playing the game.")

Tooltips:Register(interface.CoinsButton, function()
	local coins = player:GetAttribute("Coins") or 0

	return `You currently have {coins} coins.`
end, {
	MaxWidth = 260,
	BackgroundColor3 = Color3.fromRGB(35, 35, 40),
})

Tooltips:Register(interface.LockedButton, function()
	if player:GetAttribute("HasUnlockedFeature") then
		return nil
	end

	return "Complete the tutorial to unlock this feature."
end, {
	TextColor3 = Color3.fromRGB(255, 220, 120),
})

Behavior

Only one tooltip is displayed at a time.

When shown, the tooltip follows the user's cursor and automatically changes placement near the edges of the screen. It first attempts to appear below and to the right of the cursor, then flips to the opposite side when there is insufficient space.

Tooltip UI is created lazily and reused between registrations, avoiding unnecessary instance creation during repeated hovering.

📝 Notes

• TooltipCreator is intended for client-side UI and must be required from a LocalScript.
• It is designed for mouse-hover interfaces, using MouseEnter and MouseLeave internally—touch and gamepad interactions are not handled automatically.
• The module creates text-based tooltips and does not currently support arbitrary custom tooltip contents such as icons, buttons, or fully custom frames.
• Call Tooltips:Destroy() when you no longer need the instance to clean up its generated UI and connections.

🛠️ Installation

Manual installation

Place the TooltipCreator ModuleScript somewhere accessible to your client scripts.

Recommended structure:

ReplicatedStorage
└── TooltipCreator

Then require it with:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local TooltipCreator = require(ReplicatedStorage.TooltipCreator)

License

This project is available under the license included in the repository.

made with ❤️ by biotoxin495