Customizing Mouse Icons

You can customize the appearance and behavior of a user's mouse icon while they are within your experience to create a cohesive style across all of your UI elements. This includes temporarily changing the user's mouse icon in specific circumstances, such as clicking a button or while the mouse hovers over another user.

Changing Mouse Icons

You can change the user's mouse icon in a LocalScript by setting its Icon property to a custom Roblox asset ID. For example, the following LocalScript changes the user's default mouse icon to a black circle with a blue dot in the middle:


1local Players = game:GetService("Players")
2local mouse = Players.LocalPlayer:GetMouse()
3mouse.Icon = "rbxassetid://3400146391"
4

Because the icon is set in a LocalScript, each user can have a different icon, or can have an icon appear in certain situations, such as when an ability is recharging or the mouse is hovering over a hostile target.

Hiding Mouse Icons

You can hide the user's mouse icon by setting the UserInputService.MouseIconEnabled to false in a LocalScript. For example, the following code switches the mouse icon from visible to invisible and back every two seconds:


1local UserInputService = game:GetService("UserInputService")
2
3while true do
4 wait(2)
5 UserInputService.MouseIconEnabled = false
6 wait(2)
7 UserInputService.MouseIconEnabled = true
8end
9

Locking Mouse Icon Positions

You can lock the mouse icon position to the screen using UserInputService.MouseBehavior with a value of MouseBehavior.LockCurrentPosition or MouseBehavior.LockCenter. When you set this property back to MouseBehavior.Default, the mouse icon unlocks and can move anywhere on the screen again.

If a user's mouse icon is locked in a position, UserInputService.InputChanged still fires when the user moves the mouse, passing in the distance the mouse has moved. For example, the following code sample locks the user's mouse icon after one second, then Studio prints the mouse delta whenever the user moves their mouse:


1local UserInputService = game:GetService("UserInputService")
2
3wait(1)
4
5UserInputService.MouseBehavior = Enum.MouseBehavior.LockCurrentPosition
6
7UserInputService.InputChanged:Connect(function(inputObject)
8 if inputObject.UserInputType == Enum.UserInputType.MouseMovement then
9 print("Mouse delta is (" .. tostring(inputObject.Delta.X) .. ", " .. tostring(inputObject.Delta.Y) .. ")")
10 end
11end)
12