The UIDragDetector instance facilitates and encourages interaction with 2D user interface elements in an experience, 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.
For drag detectors that manipulate 3D objects in an experience, such as opening doors and drawers or sliding a part around, see 3D Drag Detectors.
Making UI Elements Draggable
To make any GuiObject instances draggable, simply add a UIDragDetector as a direct descendant.
In the Explorer window, hover over the GuiObject instance and click the ⊕ button. A contextual menu displays.
From the menu, insert a UIDragDetector.
By default, the object will now be draggable in the LayerCollector interface.
Remember that UIDragDetectors only work in Studio if you're not using the Select, Move, Scale, or Rotate tools, nor certain plugins or Studio's UI editor tools.
Customizing 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, Enum.UIDragDetectorDragStyle.TranslatePlane produces translation in the 2D plane of the LayerCollector, while Enum.UIDragDetectorDragStyle.Rotate normally produces a rotation instead of translation.
| Setting | Description |
|---|---|
| TranslateLine | 1D motion along the detector's DragAxis. |
| TranslatePlane | 2D motion in the plane of the LayerCollector. |
| Rotate | By default, rotation about the absolute center position of the detector's parent GuiObject. If ReferenceUIInstance is set, rotation happens about that instance's absolute center position. |
| Scriptable | Calculates desired motion via a custom function provided through SetDragStyleFunction(). |
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.
| Setting | Description | Default |
|---|---|---|
| ReferenceUIInstance | A GuiObject instance whose local space and absolute center position is the reference space and origin for the detector. Setting this reference affects properties such as DragUDim2, DragRotation, and the behavior of DragAxis. | nil |
| DragAxis | Vector2 value that defines the axis of movement for the dragged object when DragStyle is set to Enum.UIDragDetectorDragStyle.TranslateLine. The axis is defined in the local space of the UIDragDetector unless ReferenceUIInstance is defined, in which case the axis is defined in that instance's local space. | (1,0) |
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.
| Setting | Description |
|---|---|
| Offset | Move by the Offset values of the detector's parent's GuiObject.Position value. This is the setting by default. |
| Scale | Move by the Scale values of the detector's parent's GuiObject.Position value. |
| CustomOffset | The UI element will not move at all, but the Offset values of the detector's DragUDim2 will still be updated and the detector's events will still fire, allowing you to respond to drag manipulation however you'd like. |
| CustomScale | The UI element will not move at all, but the Scale values of the detector's DragUDim2 will still be updated and the detector's events will still fire, allowing you to respond to drag manipulation however you'd like. |
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.
| Properties | Description | Default |
|---|---|---|
| MinDragTranslation MaxDragTranslation | Limits to drag translation in each dimension, defined by a UDim2 value. If MaxDragTranslation is greater than MinDragTranslation, translation will be clamped within that range. | {0,0},{0,0} |
| MinDragAngle MaxDragAngle | Only relevant if DragStyle is set to Enum.UIDragDetectorDragStyle.Rotate, or if the functions set through SetDragStyleFunction() or AddConstraintFunction() defines a rotation value. If MaxDragAngle is greater than MinDragAngle, rotation will be clamped within that range. | 0 |
| BoundingBehavior | Determines the UIDragDetector instance's bounding behavior when its BoundingUI is set. Setting this to EntireObject bounds the entire dragged UI within the BoundingUI, while setting it to HitPoint bounds the dragged UI only by the exact hit/grab point and its respective position after translation/rotation. As a convenience, the default of Automatic mimics the EntireObject behavior for a UI object that's entirely contained by the BoundingUI, or else HitPoint for a UI object that's partially outside the BoundingUI. | Automatic |
Scripting 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.
For user-initiated script responses like Event Signals and Scripted Drag Style, you'll most commonly need to put your script code inside a LocalScript, or a Script with RunContext set to Client.
Event Signals
Through the following event signals, you can detect when a user starts, continues, and ends dragging an object.
| Event | Description |
|---|---|
| DragStart | Fires when a user starts dragging the object. |
| DragContinue | Fires when a user continues dragging the object after DragStart has been initiated. |
| DragEnd | Fires when a user stops dragging the 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.
To test this example, download the TransparencySlider.rbxm file, right‑click StarterGui in the Explorer window, select InsertfromFile, and choose the downloaded file.
UIDragDetector - Event Signal Transparency Change
-- 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)
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().
To test this example, download the HueRotator.rbxm file, right‑click StarterGui in the Explorer window, select InsertfromFile, and choose the downloaded file.
UIDragDetector - DragRotation Change
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 Enum.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 Enum.UIDragDetectorDragSpace.Relative.
UIDragDetector - Drag Following Sine Wave
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.
Multiple constraint functions can be registered and they will be called in the order of their priority value passed in upon registration, from least to greatest.
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 Enum.UIDragDetectorResponseStyle.Scale and its BoundingUI is set to the grid container.
To test this example, download the GridDrag.rbxm file, right‑click StarterGui in the Explorer window, select InsertfromFile, and choose the downloaded file.
UIDragDetector - Drag in Grid, Snapping to Tiles
-- 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)
