UI drag detectors

The UIDragDetector instance facilitates and encourages interaction with 2D user interface elements in a game, such as sliders, spinners, and more. Key features include:

• Place a UIDragDetector under any GuiObject instance to make it draggable via all user inputs without a single line of code.

• Choose from several DragStyle options, define how the object responds to motion via ResponseStyle, and optionally apply axis, movement limits, or drag boundaries.

• Scripts can respond to manipulation of dragged objects to drive logic responses, such as adjusting settings.

• UIDragDetectors work in Studio's edit and play mode as long as you're not using the Select, Move, Scale, or Rotate tools, nor certain plugins or Studio's UI editor tools.

Make UI elements draggable#

To make any GuiObject instances draggable, simply add a UIDragDetector as a direct descendant.

1. In the Explorer window, hover over the GuiObject instance and click the ⊕ button. A contextual menu displays.

2. From the menu, insert a UIDragDetector.

   

3. By default, the object will now be draggable in the LayerCollector interface.

Customize UI drag detectors#

Drag style#

UIDragDetectors map cursor motion to calculate proposed 2D motion and/or rotation. Through the DragStyle property, you can choose from different mappings to suit your needs. For example, UIDragDetectorDragStyle.TranslatePlane produces translation in the 2D plane of the LayerCollector, while UIDragDetectorDragStyle.Rotate normally produces a rotation instead of translation.

Drag direction#

By default, 2D motion and the associated DragStyle map to the space of the ancestor LayerCollector. However, you may want to change the ReferenceUIInstance or the DragAxis when building different UI components.

Response to motion#

The UIDragDetector.ResponseStyle property specifies how an object's position value is changed by the proposed motion. The custom response styles let you use the resulting UIDragDetector.DragUDim2 and UIDragDetector.DragRotation values as desired, without having the detector's parent execute the proposed motion.

Translation & rotation limits#

By default, there are no limits to 2D motion behind the inherent restrictions of the DragStyle. Limits for both minimum and maximum translations and rotations can be declared with the following properties if desired. Additionally, you can define how the dragged object is constrained within the bounds of a specified GuiObject such as a Frame.

Speed adjustments#

Through SelectionModeDragSpeed and SelectionModeRotateSpeed, you can fine‑tune the maximum drag/rotate speeds for a detector. Furthermore, through UIDragSpeedAxisMapping, you can fine‑tune the X/Y dimension dragging speeds, based on the detector's SelectionModeDragSpeed.

Script responses to clicking and dragging#

Through event signals, property changes, Scriptable drag style, and custom functions, scripts can respond to the manipulation of dragged UI elements to drive various settings or make logical decisions, such as sliders that adjust music and sound effect volume separately.

Event signals#

Through the following event signals, you can detect when a user starts, continues, and ends dragging an object.

The following slider designates its container as the BoundingUI to limit its movement within the container area, allowing the scale‑based TranslateLine drag to be limited to the full width of the container without extra scripting.

-- Hierarchy is SliderContainer ⟩ Handle ⟩ UIDragDetector ⟩ (this script)
local sliderContainer = script.Parent.Parent.Parent
local handle = sliderContainer:FindFirstChild("Handle")
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Set dragging by scale
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- Restricts dragging to line
uiDragDetector.BoundingUI = sliderContainer

-- Initially set container transparency to X scale value of handle
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- Expand handle border to indicate grab start
uiDragDetector.DragStart:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)

-- Change transparency by how much it dragged in scale
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- Revert handle border to indicate grab end
uiDragDetector.DragEnd:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)

Position & rotation changes#

In addition to event signals, you can monitor changes to the detector's DragUDim2 and/or DragRotation properties directly.

The following detector has its DragStyle set to Rotate, allowing users to drag the handle around the hue rotator ring, all while detecting changes to drag rotation through Instance:GetPropertyChangedSignal().

local handle = script.Parent.Parent  -- UI element to drag
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- Set drag style to rotate

local function changeHue()
	local currAngle = (math.fmod(handle.Rotation, 360)) / 360
	if currAngle < 0 then
		currAngle += 1
	end
	handle.BackgroundColor3 = Color3.fromHSV(currAngle, 1, 1)
end

-- Initially set hue to handle rotation
changeHue()

-- Connect function to GetPropertyChangedSignal() of the detector's drag rotation
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)

Scripted drag style#

If you set a detector's UIDragDetector.DragStyle to UIDragDetectorDragStyle.Scriptable, you can provide your own function that takes in a Vector2 of the input position and returns a UDim2 (position) and a float (rotation). The detector will update the object to the computed position/rotation based off of the returns, the DragSpace property, and the DragRelativity property.

By default, the returned UDim2 and float will be the final desired position/rotation in the local space of the detector's parent. Existing translation/rotation limits will still apply, as will boundary limits imposed by a specified BoundingUI instance.

The following example drags a UI element following a sine wave computed by the change in X coordinate input. Note that the detector's DragSpace is set to UIDragDetectorDragSpace.Relative.

local frame = script.Parent  -- UI element to drag
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- Lower this value to increase frequency

uiDragDetector.DragStart:Connect(function(inputPosition)
	initialXValue = inputPosition.X
end)

local function computeSinWaveCoordinate(inputPosition)
	local deltaX = inputPosition.X - initialXValue
	-- Negative Y delta so that it goes "up" on the screen with positive Y change
	local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
	return UDim2.fromOffset(deltaX, deltaY)
end

uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)

Custom constraint function#

UIDragDetectors do not have built-in motion rules about grids and snapping, but you can register custom constraint functions to edit the detector's UIDragDetector.DragUDim2 and UIDragDetector.DragRotation before they are applied. For example, you can keep motion on a grid by rounding positions to specific increments, or define allowed areas of motion. Note that this is applied before any existing translation/rotation limits.

The following example utilizes a constraint function that clamps the planar drag into an X/Y grid based on the number of rows and columns. Note that the detector's ResponseStyle is set to UIDragDetectorResponseStyle.Scale and its BoundingUI is set to the grid container.

-- Hierarchy is GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (this script)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- UI element to drag
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- Set dragging by scale
uiDragDetector.DragRelativity = Enum.UIDragDetectorDragRelativity.Relative
uiDragDetector.BoundingUI = gridContainer

local NUM_COLUMNS = 10
local NUM_ROWS = 5

local xScaleIncrement = 1 / NUM_COLUMNS
local yScaleIncrement = 1 / NUM_ROWS
local initialParentPosition = uiDragDetector.Parent.Position

uiDragDetector.DragStart:Connect(function()
	initialParentPosition = uiDragDetector.Parent.Position
end)

local function dragToGridOnly(proposedPosition, proposedRotation)
	local griddedXScale = math.round(proposedPosition.X.Scale / xScaleIncrement) * xScaleIncrement
	local griddedYScale = math.round(proposedPosition.Y.Scale / yScaleIncrement) * yScaleIncrement

	return UDim2.fromScale(griddedXScale, griddedYScale), proposedRotation
end

uiDragDetector:AddConstraintFunction(1, dragToGridOnly)