18 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

UIDragDetector

Inherits from: UIComponent → UIBase → Instance → Object

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

Inherits from: UIComponent

Memory category: Instances

Properties

NameType / ReturnsDescription
UIDragDetector.ActivatedCursorIconContentIdSets the cursor icon to display when the mouse is activated over the parent of this UIDragDetector.
UIDragDetector.ActivatedCursorIconContentContentSets the cursor icon to display when the mouse is activated over the parent of this UIDragDetector. Only supports asset URIs
UIDragDetector.BoundingBehaviorUIDragDetectorBoundingBehaviorDetermines bounding behavior of the dragged UI object when the detector's BoundingUI is set.
UIDragDetector.BoundingUIGuiBase2dInstance whose bounding area defines the drag boundaries for the parent GuiObject.
UIDragDetector.CursorIconContentIdSets the cursor icon to display when the mouse is hovered over the parent of this UIDragDetector.
UIDragDetector.CursorIconContentContentSets the cursor icon to display when the mouse is hovered over the parent of this UIDragDetector. Only asset URIs are supported.
UIDragDetector.DragAxisVector2The drag axis for the UIDragDetector instance when DragStyle is set to UIDragDetectorDragStyle.TranslateLine.
UIDragDetector.DragRelativityUIDragDetectorDragRelativitySets the paradigm which defines the relativity of inputs/outputs from a custom drag function.
UIDragDetector.DragRotationfloatThe rotation performed by the current drag.
UIDragDetector.DragSpaceUIDragDetectorDragSpaceSets the paradigm which defines the space of inputs/outputs from a custom drag function.
UIDragDetector.DragStyleUIDragDetectorDragStyleThe paradigm used to generate proposed motion.
UIDragDetector.DragUDim2UDim2The translation performed by the current drag expressed in a UDim2 value.
UIDragDetector.EnabledbooleanWhether the UIDragDetector responds to user input.
UIDragDetector.MaxDragAnglefloatAlong with MinDragAngle, impedes the detector's attempts to generate rotational motion.
UIDragDetector.MaxDragTranslationUDim2Along with MinDragTranslation, impedes the detector's attempts to generate linear/planar motion.
UIDragDetector.MinDragAnglefloatAlong with MaxDragAngle, impedes the detector's attempts to generate rotational motion.
UIDragDetector.MinDragTranslationUDim2Along with MaxDragTranslation, impedes the detector's attempts to generate linear/planar motion.
UIDragDetector.ReferenceUIInstanceGuiObjectA GuiObject instance whose local space and absolute center position is the reference space and origin for the detector.
UIDragDetector.ResponseStyleUIDragDetectorResponseStyleThe paradigm used to define the response to proposed motion.
UIDragDetector.SelectionModeDragSpeedUDim2Maximum drag speed for translation.
UIDragDetector.SelectionModeRotateSpeedfloatMaximum angle per second the UIDragDetector can rotate at.
UIDragDetector.UIDragSpeedAxisMappingUIDragSpeedAxisMappingUIDragSpeedAxisMapping value that determines the X/Y dimension dragging speeds.

Inherited from Instance

NameType / ReturnsDescription
Instance.ArchivablebooleanDetermines if an Instance and its descendants can be cloned using Instance:Clone(), and can be saved/published.
Instance.archivableboolean
Instance.CapabilitiesSecurityCapabilitiesThe set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandboxbooleanIndicates whether the instance is inside a sandboxed container.
Instance.NamestringA non-unique identifier of the Instance.
Instance.ParentInstanceDetermines the hierarchical parent of the Instance.
Instance.PredictionModePredictionModeReflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLockedbooleanA deprecated property that used to protect CoreGui objects.
Instance.SandboxedbooleanWhen enabled, the instance can only access abilities in its Capabilities list.
Instance.UniqueIdUniqueIdA unique identifier for the instance.

Inherited from Object

NameType / ReturnsDescription
Object.ClassNamestringA read-only string representing the class this Object belongs to.
Object.classNamestring

UIDragDetector.ActivatedCursorIcon

Sets the cursor icon to display when the mouse is activated over the parent of this UIDragDetector. If this property is left blank, the detector will use the default icon.

To change the activated cursor icon, set this property to the asset ID of the image you'd like to use.

FieldValue
typeContentId
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryImage
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.ActivatedCursorIconContent

Sets the cursor icon to display when the mouse is activated over the parent of this UIDragDetector. If this property is left blank, the detector will use the default icon.

To change the activated cursor icon, set this property to the asset ID of the image you'd like to use. Only asset URIs are supported for this property.

FieldValue
typeContent
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryImage
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.BoundingBehavior

Determines bounding behavior of the dragged UI object when the detector's BoundingUI is set. See UIDragDetectorBoundingBehavior for details on each setting's behavior.

FieldValue
typeUIDragDetectorBoundingBehavior
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.BoundingUI

When set, the UIDragDetector instance will not allow the bounds of the parent GuiObject to be dragged outside the bounds of the BoundingUI instance.

Note that if a portion of the parent GuiObject is outside the BoundingUI bounds, the initial input position at drag start and its relative position during drag will be used for bounding detection until the entirety of the dragged object is within the bounds, after which the object will be constrained inside the bounds.

FieldValue
typeGuiBase2d
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.CursorIcon

Sets the cursor icon to display when the mouse is hovered over the parent of this UIDragDetector. If this property is left blank, the detector will use the default icon.

To change the cursor icon, set this property to the asset ID of the image you'd like to use.

FieldValue
typeContentId
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryImage
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.CursorIconContent

Sets the cursor icon to display when the mouse is hovered over the parent of this UIDragDetector. If this property is left blank, the detector will use the default icon.

To change the cursor icon, set this property to the asset ID of the image you'd like to use. Only asset URIs are supported for this property.

FieldValue
typeContent
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryImage
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragAxis

Vector2 value that defines the axis of movement for the dragged object when DragStyle is set to 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.

FieldValue
typeVector2
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDrag Directions
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragRelativity

Only applies if a custom drag function is registered through SetDragStyleFunction() or AddConstraintFunction(). Sets the paradigm which defines the relativity of the registered function's inputs/outputs.

For example, returning a UDim2.fromOffset(1, 0) from a registered function with this property set to UIDragDetectorDragRelativity.Absolute will move the detector's parent to (1, 0) in the designated DragSpace, while returning the same UDim2 with this property set to UIDragDetectorDragRelativity.Relative will move the detector's parent by (1, 0) in the designated DragSpace.

FieldValue
typeUIDragDetectorDragRelativity
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragRotation

The rotation performed by the current drag. This value is defined in degrees relative to the local space of the UIDragDetector unless ReferenceUIInstance is defined, in which case the rotation is defined in the local space of that instance and from its positive X axis.

This property can be changed while there is no active drag to rotate the dragged object.

FieldValue
typefloat
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDragged Amount
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragSpace

Only applies if a custom drag function is registered through SetDragStyleFunction() or AddConstraintFunction(). Sets the paradigm which defines the space of the registered function's inputs/outputs.

For example, if the detector's parent GuiObject is a child of a parent GuiObject that's rotated:

FieldValue
typeUIDragDetectorDragSpace
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragStyle

The paradigm used to generate proposed motion, given a stream of input position vectors. See UIDragDetectorDragStyle for options.

FieldValue
typeUIDragDetectorDragStyle
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.DragUDim2

The translation performed by the current drag expressed in a UDim2 value. Translation is done through Offset or Scale value changes depending on the DragRelativity value, and it is relative to the detector's local space unless a ReferenceUIInstance is defined.

This property can be changed while there is no active drag to move the dragged object.

FieldValue
typeUDim2
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDragged Amount
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.Enabled

If true, the UIDragDetector responds to user input; if false, it does not.

FieldValue
typeboolean
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.MaxDragAngle

If this property is greater than MinDragAngle, rotation will be clamped within the range of MinDragAngle and MaxDragAngle. Positive values impede clockwise rotation while negative values impede counterclockwise rotation.

This is not a constraint; it merely impedes the detector's attempts to generate motion in order to remain within limits. See AddConstraintFunction() to add custom constraint to a drag.

Only relevant if DragStyle is UIDragDetectorDragStyle.Rotate.

FieldValue
typefloat
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDrag Limits
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.MaxDragTranslation

If the corresponding Offset and/or Scale values are greater than those of MinDragTranslation in all dimensions, linear/planar translation will be clamped within the range of MinDragTranslation and MaxDragTranslation.

This is not a constraint; it merely impedes the detector's attempts to generate motion in order to remain within limits. See AddConstraintFunction() to add custom constraint to a drag.

Only relevant if DragStyle is UIDragDetectorDragStyle.TranslateLine or UIDragDetectorDragStyle.TranslatePlane.

FieldValue
typeUDim2
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDrag Limits
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.MinDragAngle

If this property is less than MaxDragAngle, rotation will be clamped within the range of MinDragAngle and MaxDragAngle. Positive values impede clockwise rotation while negative values impede counterclockwise rotation.

This is not a constraint; it merely impedes the detector's attempts to generate motion in order to remain within limits. See AddConstraintFunction() to add custom constraint to a drag.

Only relevant if DragStyle is UIDragDetectorDragStyle.Rotate.

FieldValue
typefloat
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDrag Limits
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.MinDragTranslation

If the corresponding Offset and/or Scale values are less than those of MaxDragTranslation in all dimensions, linear/planar translation will be clamped within the range of MinDragTranslation and MaxDragTranslation.

This is not a constraint; it merely impedes the detector's attempts to generate motion in order to remain within limits. See AddConstraintFunction() to add custom constraint to a drag.

Only relevant if DragStyle is UIDragDetectorDragStyle.TranslateLine or UIDragDetectorDragStyle.TranslatePlane.

FieldValue
typeUDim2
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryDrag Limits
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.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.

FieldValue
typeGuiObject
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.ResponseStyle

Once the proposed motion has been computed and potentially constrained, this paradigm is used to deterimine how to move (or not move) the GuiObject affected by the UIDragDetector. See UIDragDetectorResponseStyle for options.

FieldValue
typeUIDragDetectorResponseStyle
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.SelectionModeDragSpeed

Defines the maximum drag speed for translation as a combination of Scale and Offset of the first ancestor ScreenGui or SurfaceGui the UIDragDetector belongs to. This value must be positive and any value below 0 will be clamped to 0.

FieldValue
typeUDim2
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.SelectionModeRotateSpeed

Defines the maximum angle per second at which the UIDragDetector can rotate. This value must be positive and any value below 0 will be clamped to 0.

FieldValue
typefloat
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

UIDragDetector.UIDragSpeedAxisMapping

UIDragSpeedAxisMapping value that determines the X/Y dimension dragging speeds.

FieldValue
typeUIDragSpeedAxisMapping
security{"read":"None","write":"None"}
thread safetyReadSafe
categoryBehavior
serialization{"can_load":true,"can_save":true}
capabilities["UI"]

Methods

NameType / ReturnsDescription
UIDragDetector:AddConstraintFunctionRBXScriptConnectionAdds a function to modify or constrain proposed motion.
UIDragDetector:GetReferencePositionUDim2Returns the reference UDim2 position of the current drag's reference origin.
UIDragDetector:GetReferenceRotationfloatReturns the reference rotation of the current drag's reference element.
UIDragDetector:SetDragStyleFunction()Passes a function to be used if and only if DragStyle is set to UIDragDetectorDragStyle.Scriptable.

Inherited from Instance

NameType / ReturnsDescription
Instance:AddTag()Applies a tag to the instance.
Instance:childrenInstancesReturns an array of the object's children.
Instance:ClearAllChildren()This method destroys all of an instance's children.
Instance:CloneInstanceCreate a copy of an instance and all its descendants, ignoring instances that are not Archivable.
Instance:cloneInstance
Instance:Destroy()Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children.
Instance:destroy()
Instance:FindFirstAncestorInstance?Returns the first ancestor of the Instance whose Instance.Name is equal to the given name.
Instance:FindFirstAncestorOfClassInstance?Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className.
Instance:FindFirstAncestorWhichIsAInstance?Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className.
Instance:FindFirstChildInstance?Returns the first child of the Instance found with the given name.
Instance:findFirstChildInstance
Instance:FindFirstChildOfClassInstance?Returns the first child of the Instance whose ClassName is equal to the given class name.
Instance:FindFirstChildWhichIsAInstance?Returns the first child of the Instance for whom Object:IsA() returns true for the given className.
Instance:FindFirstDescendantInstance?Returns the first descendant found with the given Instance.Name.
Instance:GetActorActor?Returns the Actor associated with the Instance, if any.
Instance:GetAttributeVariantReturns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignalRBXScriptSignalReturns an event that fires when the given attribute changes.
Instance:GetAttributesDictionaryReturns a dictionary of the instance's attributes.
Instance:GetChildrenInstancesReturns an array containing all of the instance's children.
Instance:getChildrenInstances
Instance:GetDebugIdstringReturns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendantsInstancesReturns an array containing all of the descendants of the instance.
Instance:GetFullNamestringReturns a string describing the instance's ancestry.
Instance:GetStyledVariantReturns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignalRBXScriptSignalReturns an event that fires when the given style property changes on the instance.
Instance:GetTagsArrayGets an array of all tags applied to the instance.
Instance:HasTagbooleanCheck whether the instance has a given tag.
Instance:IsAncestorOfbooleanReturns true if an Instance is an ancestor of the given descendant.
Instance:IsDescendantOfbooleanReturns true if an Instance is a descendant of the given ancestor.
Instance:isDescendantOfboolean
Instance:IsPropertyModifiedbooleanReturns true if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendantsInstancesReturns an array containing all descendants of the instance that match the selector string.
Instance:Remove()Sets the object's Parent to nil, and does the same for all its descendants.
Instance:remove()
Instance:RemoveTag()Removes a tag from the instance.
Instance:ResetPropertyToDefault()Resets a property to its default value.
Instance:SetAttribute()Sets the attribute with the given name to the given value.
Instance:WaitForChildInstanceReturns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

NameType / ReturnsDescription
Object:GetPropertyChangedSignalRBXScriptSignalGet an event that fires when a given property of the object changes.
Object:IsAbooleanReturns true if an object's class matches or inherits from a given class.
Object:isAboolean

UIDragDetector:AddConstraintFunction

Adds a function to modify or constrain proposed motion. The function takes an input UDim2 (position) and float (rotation) of proposed motion and returns a UDim2 and float of modified or unmodified motion. You can add multiple functions which will be called in order by priority, passing the results along in a chain.

The input is expressed in the space defined by the DragSpace property, either as a delta or the final desired position/rotation based on the DragRelativity property. The output should be expressed in the same space and relativity, unless overridden by returning a specified UIDragDetectorDragRelativity and UIDragDetectorDragSpace as the third and fourth return values.

To remove an added constraint function, call Disconnect() on the returned connection object.

Parameters

NameTypeDefaultDescription
priorityintThe order of priority for functions added via this method. Higher values take precedence over lower values.
functionFunctionFunction for modifying or constraining proposed motion. This function takes in input UDim2 and float of proposed motion and returns a UDim2 and float of modified or unmodified motion. It can optionally return an UIDragDetectorDragRelativity and UIDragDetectorDragSpace as the third and fourth return values as output overrides.

Returns

TypeDescription
RBXScriptConnectionUse this connection object to remove the constraint function.
FieldValue
securityNone
thread safetyUnsafe
capabilities["UI"]

UIDragDetector:GetReferencePosition

When no ReferenceUIInstance is set, this function returns the UDim2 position of the dragged object's immediate parent GuiObject (if one exists), or else the UDim2 position of the dragged object.

When a ReferenceUIInstance is set, this function returns the UDim2 position of that reference instance.

Returns

TypeDescription
UDim2UDim2 position of the current drag's reference element.
FieldValue
securityNone
thread safetyUnsafe
capabilities["UI"]

UIDragDetector:GetReferenceRotation

When no ReferenceUIInstance is set, this function returns the rotation of the dragged object's immediate parent GuiObject (if one exists), or else the rotation of the dragged object.

When a ReferenceUIInstance is set, this function returns the rotation of that reference instance.

Returns

TypeDescription
floatRotation of the current drag's reference element.
FieldValue
securityNone
thread safetyUnsafe
capabilities["UI"]

UIDragDetector:SetDragStyleFunction

Passes a function to be used if and only if DragStyle is set to UIDragDetectorDragStyle.Scriptable. The given function receives the signal's screen space input position with type Vector2, and it returns a UDim2 (position) and float (rotation) containing the desired motion of the drag. The space of the return values and the relativity of the motion are determined by the DragSpace and DragRelativity properties, unless overridden by returning a specified UIDragDetectorDragRelativity and UIDragDetectorDragSpace as the third and fourth return values.

If the function returns nil, the object will not be moved. This is useful if the script has not yet collected all the information it needs to give the correct answer, or in temporary cases where you want the object to stay where it is.

Parameters

NameTypeDefaultDescription
functionFunctionFunction for monitoring DragContinue signals. This function receives the signal's screen space input position and returns a UDim2 and float containing the desired motion of the drag in the desired space and relativity. If this function returns nil, the object will not be moved.

Returns

TypeDescription
()
FieldValue
securityNone
thread safetyUnsafe
capabilities["UI"]

Events

NameType / ReturnsDescription
UIDragDetector.DragContinueFires when a user continues dragging the UI element after DragStart has been initiated.
UIDragDetector.DragEndFires when a user stops dragging the UI element.
UIDragDetector.DragStartFires when a user starts dragging the UI element.

Inherited from Instance

NameType / ReturnsDescription
Instance.AncestryChangedFires when the Instance.Parent property of this object or one of its ancestors is changed.
Instance.AttributeChangedFires whenever an attribute is changed on the Instance.
Instance.ChildAddedFires after an object is parented to this Instance.
Instance.childAdded
Instance.ChildRemovedFires after a child is removed from this Instance.
Instance.DescendantAddedFires after a descendant is added to the Instance.
Instance.DescendantRemovingFires immediately before a descendant of the Instance is removed.
Instance.DestroyingFires immediately before (or is deferred until after) the instance is destroyed via Instance:Destroy().
Instance.StyledPropertiesChangedFires whenever any style property is changed on the instance, including when a property is set to nil.

Inherited from Object

NameType / ReturnsDescription
Object.ChangedFires immediately after a property of the object changes, with some limitations.

UIDragDetector.DragContinue

Fires when a user continues dragging the UI element after DragStart has been initiated.

Parameters

NameTypeDefaultDescription
inputPositionVector2Vector2 representing the current input position.
FieldValue
securityNone
capabilities["UI"]

UIDragDetector.DragEnd

Fires when a user stops dragging the UI element.

Parameters

NameTypeDefaultDescription
inputPositionVector2Vector2 representing the current input position.
FieldValue
securityNone
capabilities["UI"]

UIDragDetector.DragStart

Fires when a user starts dragging the UI element.

Parameters

NameTypeDefaultDescription
inputPositionVector2Vector2 representing the current input position.
FieldValue
securityNone
capabilities["UI"]