{"id":"biotoxin495/tooltipmanager","name":"tooltipmanager","scope":"biotoxin495","platform":"roblox","description":"A lightweight, standalone tooltip utility for displaying a configurable text tooltip while the mouse is hovering over a GuiObject.","version":"1.0.3","latest":"1.0.3","versions":["1.0.0","1.0.1","1.0.2","1.0.3"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"3931f17b13822a63f6884a7f081d0075a5cad21f10e57346539d7055104705ab","likes":0,"downloads":0,"install":"forest install biotoxin495/tooltipmanager","url":"https://forest.dev/p/roblox/biotoxin495/tooltipmanager","files":"https://api.forest.dev/ai/package/roblox/biotoxin495/tooltipmanager/files","readme":"# TooltipCreator — A lightweight tooltip utility for Roblox UI\n\n**TooltipCreator**, a lightweight, standalone tooltip utility for Roblox interfaces.\n\nTooltipCreator 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.\n\nThe module handles tooltip creation, cursor tracking, viewport-aware positioning, delayed display, dynamic text, and cleanup internally, while keeping the public API small and simple.\n\n## Quick example\n\nTooltipCreator attaches to any `GuiObject` through `Register`.\n\n```lua\nlocal TooltipCreator = require(ReplicatedStorage.TooltipCreator)\n\nlocal Tooltips = TooltipCreator.new()\n\nTooltips:Register(script.Parent.PlayButton, \"Start playing the game.\")\n```\n\nThe tooltip appears automatically while the mouse hovers over `PlayButton` and disappears when the mouse leaves. Everything else—positioning, delay, and cleanup—is handled internally.\n\n## 🚀 Features\n\n### Hover-based tooltips\n\nRegister a tooltip on any `GuiObject` and TooltipCreator handles the rest.\n\n```lua\nTooltips:Register(script.Parent.PlayButton, \"Start playing the game.\")\n```\n\nTooltips appear on `MouseEnter` and disappear on `MouseLeave`, with an optional delay before showing.\n\n### Dynamic tooltips\n\nTooltip 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.\n\n```lua\nTooltips:Register(script.Parent.CoinsButton, function()\n\tlocal coins = player:GetAttribute(\"Coins\") or 0\n\n\treturn `You currently have {coins} coins.`\nend)\n```\n\nReturning `nil` or an empty string from the callback prevents the tooltip from being shown.\n\n### Viewport-aware positioning\n\nTooltips 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.\n\n### Configurable appearance\n\nEach registered tooltip may override text, color, sizing, and layout independently of the global defaults.\n\n```lua\nTooltips:Register(script.Parent.SettingsButton, \"Open the settings menu.\", {\n\tTextSize = 16,\n\tBackgroundColor3 = Color3.fromRGB(30, 30, 34),\n\tCornerRadius = UDim.new(0, 6),\n})\n```\n\n### Efficient by design\n\nTooltipCreator reuses a single tooltip instance across all registrations instead of creating new UI for every hover, and automatically unregisters elements once they're destroyed.\n\n### Fully typed, no dependencies\n\nThe module ships with a fully typed Luau API and has no external dependencies or framework requirements.\n\n## 📖 Basic usage\n\nPlace the `TooltipCreator` ModuleScript somewhere accessible to your client scripts, such as `ReplicatedStorage`. TooltipCreator must be required and used from a `LocalScript`.\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal TooltipCreator = require(ReplicatedStorage.TooltipCreator)\n\nlocal Tooltips = TooltipCreator.new()\n\nTooltips:Register(\n\tscript.Parent.PlayButton,\n\t\"Start playing the game.\"\n)\n```\n\n### Example: dynamic coin counter tooltip\n\n```lua\nTooltips:Register(script.Parent.CoinsButton, function()\n\tlocal coins = player:GetAttribute(\"Coins\") or 0\n\n\treturn `You currently have {coins} coins.`\nend, {\n\tMaxWidth = 260,\n\tBackgroundColor3 = Color3.fromRGB(35, 35, 40),\n})\n```\n\n### Example: conditionally hidden tooltip\n\n```lua\nTooltips:Register(script.Parent.LockedButton, function()\n\tif player:GetAttribute(\"HasUnlockedFeature\") then\n\t\treturn nil\n\tend\n\n\treturn \"Complete the tutorial to unlock this feature.\"\nend, {\n\tTextColor3 = Color3.fromRGB(255, 220, 120),\n})\n```\n\n### Example: custom global configuration\n\n```lua\nlocal Tooltips = TooltipCreator.new({\n\tName = \"GameTooltips\",\n\tDisplayOrder = 1000,\n\tEdgePadding = 6,\n\tDefaultShowDelay = 0.15,\n})\n```\n\n## ⚙️ API\n\n### `TooltipCreator.new(config?)`\n\nCreates a new TooltipCreator instance. An optional configuration table may be provided to customize global behavior.\n\n```lua\nlocal Tooltips = TooltipCreator.new()\n```\n\n### `Tooltips:Register(trigger, text, options?)`\n\nRegisters or updates a tooltip for a `GuiObject`.\n\n```lua\nTooltips:Register(Button, \"Tooltip text\")\n```\n\n`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.\n\n### `Tooltips:Unregister(trigger)`\n\nRemoves a previously registered tooltip and disconnects its associated events.\n\n```lua\nTooltips:Unregister(Button)\n```\n\nRegistered elements are also automatically unregistered when they are destroyed.\n\n### `Tooltips:SetEnabled(enabled)`\n\nGlobally enables or disables tooltip display.\n\n```lua\nTooltips:SetEnabled(false)\n```\n\nDisabling tooltips immediately hides the active tooltip. Registered tooltips remain stored and can be restored by enabling the instance again.\n\n### `Tooltips:IsEnabled()`\n\nReturns whether tooltip display is currently enabled.\n\n```lua\nlocal enabled = Tooltips:IsEnabled()\n```\n\n### `Tooltips:Clear()`\n\nImmediately hides the currently visible tooltip, without removing any registered tooltips.\n\n```lua\nTooltips:Clear()\n```\n\n### `Tooltips:Destroy()`\n\nCompletely destroys the TooltipCreator instance.\n\n```lua\nTooltips:Destroy()\n```\n\nThis 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()`.\n\n## Complete options reference\n\nYou normally only need to provide the options you want to change. Any omitted options use the module defaults.\n\n### Tooltip options\n\nPassed per-registration as the third argument to `Register`.\n\n| Option | Type | Description |\n| --- | --- | --- |\n| `Offset` | `Vector2` | Distance between the cursor and tooltip |\n| `ShowDelay` | `number` | Delay in seconds before the tooltip appears |\n| `TextSize` | `number` | Tooltip text size |\n| `Font` | `Enum.Font` | Tooltip text font |\n| `Padding` | `Vector2` | Horizontal and vertical internal padding |\n| `MaxWidth` | `number` | Maximum text width before wrapping |\n| `TextColor3` | `Color3` | Tooltip text color |\n| `BackgroundColor3` | `Color3` | Tooltip background color |\n| `BackgroundTransparency` | `number` | Tooltip background transparency |\n| `CornerRadius` | `UDim` | Tooltip corner radius |\n| `RichText` | `boolean` | Enables Roblox rich-text formatting |\n\n### Constructor configuration\n\nPassed to `TooltipCreator.new()` to configure global behavior.\n\n| Property | Type | Description |\n| --- | --- | --- |\n| `Name` | `string` | Name assigned to the generated `ScreenGui` |\n| `DisplayOrder` | `number` | Display order of the tooltip `ScreenGui` |\n| `EdgePadding` | `number` | Minimum distance between tooltips and viewport edges |\n| `DefaultShowDelay` | `number` | Default delay used when a tooltip does not define its own |\n\n## Complete example\n\n```lua\nlocal Players = game:GetService(\"Players\")\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal TooltipCreator = require(ReplicatedStorage.TooltipCreator)\n\nlocal player = Players.LocalPlayer\nlocal interface = script.Parent\n\nlocal Tooltips = TooltipCreator.new({\n\tDefaultShowDelay = 0.15,\n\tDisplayOrder = 1000,\n})\n\nTooltips:Register(interface.PlayButton, \"Start playing the game.\")\n\nTooltips:Register(interface.CoinsButton, function()\n\tlocal coins = player:GetAttribute(\"Coins\") or 0\n\n\treturn `You currently have {coins} coins.`\nend, {\n\tMaxWidth = 260,\n\tBackgroundColor3 = Color3.fromRGB(35, 35, 40),\n})\n\nTooltips:Register(interface.LockedButton, function()\n\tif player:GetAttribute(\"HasUnlockedFeature\") then\n\t\treturn nil\n\tend\n\n\treturn \"Complete the tutorial to unlock this feature.\"\nend, {\n\tTextColor3 = Color3.fromRGB(255, 220, 120),\n})\n```\n\n## Behavior\n\nOnly one tooltip is displayed at a time.\n\nWhen 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.\n\nTooltip UI is created lazily and reused between registrations, avoiding unnecessary instance creation during repeated hovering.\n\n## 📝 Notes\n\n* TooltipCreator is intended for client-side UI and must be required from a `LocalScript`.\n* It is designed for mouse-hover interfaces, using `MouseEnter` and `MouseLeave` internally—touch and gamepad interactions are not handled automatically.\n* The module creates text-based tooltips and does not currently support arbitrary custom tooltip contents such as icons, buttons, or fully custom frames.\n* Call `Tooltips:Destroy()` when you no longer need the instance to clean up its generated UI and connections.\n\n## 🛠️ Installation\n\n### Manual installation\n\nPlace the `TooltipCreator` ModuleScript somewhere accessible to your client scripts.\n\nRecommended structure:\n\n```text\nReplicatedStorage\n└── TooltipCreator\n```\n\nThen require it with:\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal TooltipCreator = require(ReplicatedStorage.TooltipCreator)\n```\n\n## License\n\nThis project is available under the license included in the repository.\n\nmade with ❤️ by biotoxin495\n","readmeTruncated":false}