An enhanced fork of the original TiDraggable module by Pedro Enrique, allows for simple creation of "draggable" views.
- Opt-in
scrollHandoff.suppressScrollMomentumprevents an upward sheet flick from carrying residual momentum into the inner table. The first row retains its navigation-bar and safe-area positioning as the sheet expands. scrollHandoff.scrollEnabledByDetentcontrols scrolling for individual detents, including keeping collapsed content at its adjusted top throughout the transition to the next detent.- Opt-in
collapsedBounceadds progressively stronger pull resistance below the collapsed boundary and a native spring-back on release or cancellation. It is ignored while the dismiss policy is selected. - The existing detents, follower views, axis locking, and interactive/programmatic detent progress APIs remain available. The new options are disabled or unset by default.
Download the ZIP from the iOS v4.6.0 release, install it into your app or Titanium module directory, then add:
<module platform="iphone" version="4.6.0">ti.draggable</module>This iOS package requires Titanium SDK 13.2.0.GA or newer. The 4.6.0 additions apply to iOS; Android source is unchanged.
- Improved drag performance for iOS and Android.
- Updated public APIs for more seamless integration.
- Removed the InfiniteScroll class as it doesn't really have much to do with the overall module.
- Removed unnecessary APIs to reduce overall module footprint.
- Removed unused variables and organized imports.
- Added ability to unset boundaries.
- Mapped the missing
cancelgesture to theendgesture (firing the respective event). - Added
ensureRightandensureBottom, this allows for stable dragging of views where the dimensions are not known. - Added
enabledboolean property for toggeling drag - Views can be mapped and translated with a draggable view.
- iOS: Added native bottom-sheet detents, nested scroll handoff, and detent-aware follower views.
- Draggable implementation now has its own configurable property called
draggable. - iOS: Supports all Ti.UI.View subclasses and Ti.UI.View wrapped views (View, Window, Label)
- Android: Fixed a bug where touch events were not correctly passed to children or bubbled to the parent.
- Android: Fixed a bug where min and max bounds were being incorrectly reported after being set.
- Android: Improved drag tracking. It plays nice with child views now.
- Android: Added a touch threshold to ensure all child views have a chance to have their respective events fired.
var Draggable = require('ti.draggable'),
mainWindow = Ti.UI.createWindow({
backgroundColor : 'white'
}),
draggableView = Draggable.createView({
width : 100,
height : 100,
backgroundColor : 'black'
});
mainWindow.add(draggableView);
mainWindow.open();If you are building the Android module, make sure you update the .classpath and build.properties files to match your setup.
Create a draggable view. All of Titanium's properties are supported along the additional draggableConfig property containing any options that should be set upon creation. See Options
When the draggable proxy is created a new property is set called
draggablewhich stores all the configuration properties and allows for options to be updated after creation.
iOS Notes
You can pass almost all of iOS' supported Ti.UI creation methods to the draggable module such as Draggable.createView( ... ) or Draggable.createWindow( ... ). While Ti.UI.View and Ti.UI.Window are fully supported on iOS other APIs haven't been fully tested.
Android Notes Android only supports the creation of Ti.UI.Views. At this time there are no plans to add support for other APIs.
Options can be set on view creation using draggableConfig or after creation using DraggableView.draggable.setConfig( ... )
The setConfig method can set options two different ways. You can pass an object containing the parameters you with to set or you can pass a key-value pair.
Setting Options With An Object
DraggableView.draggable.setConfig('enabled', false);Setting Options With An Object
DraggableView.draggable.setConfig({
enabled : false
});Flag to enable or disable dragging.
Constrains how the view can be dragged.
Supported values:
-
x— drag horizontally only -
y— drag vertically only -
xy— drag on either axis, but only one axis at a time per gesture
When axis is set to xy, the drag locks to the first dominant direction of the gesture.
This means the view can move horizontally or vertically, but not diagonally during the same drag.
If axis is omitted, the view can move freely on both axes.
Version 4.6.0 can coordinate a vertical draggable view with a descendant Ti.UI.TableView, Ti.UI.ListView, or Ti.UI.ScrollView. The inner scroll view scrolls while the sheet is expanded. A downward gesture first returns the inner content to its adjusted top offset, then transfers the same gesture to the draggable sheet without waiting for JavaScript.
var Draggable = require('ti.draggable');
var window = Ti.UI.createWindow({ backgroundColor: '#F3F2F8' });
var rows = [];
for (var index = 1; index <= 40; index++) {
rows.push({ title: 'Nearby place ' + index, height: 58 });
}
var tableView = Ti.UI.createTableView({
top: 72,
bottom: 0,
data: rows
});
var mapButtons = Ti.UI.createView({
right: 16,
width: 48,
height: 104
});
var expandedTop = 80;
var screenHeight = Ti.Platform.displayCaps.platformHeight;
var sheet = Draggable.createView({
top: 700,
left: 0,
right: 0,
height: screenHeight - expandedTop,
draggableConfig: {
axis: 'y',
detents: {
expanded: expandedTop,
middle: 420,
collapsed: 700
},
initialDetent: 'collapsed',
collapsedBounce: { enabled: true },
progressRanges: [
{ id: 'collapsedToMiddle', from: 'collapsed', to: 'middle' },
{ id: 'middleToExpanded', from: 'middle', to: 'expanded' }
],
scrollHandoff: {
view: tableView,
atTopBehavior: 'drag',
suppressScrollMomentum: true,
scrollEnabledByDetent: { collapsed: false, middle: true, expanded: true }
},
followers: [{
view: mapButtons,
attachUntil: 'middle',
offset: -12,
fadeBetween: ['middle', 'expanded'],
passThroughTouches: true,
disableTouchesWhenHidden: true
}]
}
});
sheet.add(tableView);
window.add(mapButtons); // Followers should be siblings of the sheet.
window.add(sheet);
window.open();All scrolling, dragging, snapping, follower positioning, and fading occurs in UIKit. JavaScript can optionally observe interactive progress without driving the native motion.
detents accepts a dictionary of names and absolute top positions. Names are arbitrary and positions are sorted from smallest (expanded) to largest (collapsed). When detents are configured they also become the vertical drag bounds.
initialDetent(String) — Positions the sheet at a named detent after its native view is ready.detentVelocityThreshold(Number, default500) — Vertical velocity in points per second that advances to the next detent in the release direction.detentDuration(Number, default0.42) — Native snap duration in seconds.detentDamping(Number, default0.86) — Native snap spring damping ratio from0.01through1.0.
Move to a detent programmatically:
sheet.draggable.setDetent('middle');
sheet.draggable.setDetent('expanded', { animated: false });
sheet.draggable.setDetent('expanded', { animated: true, updateProgress: true });collapsedBounce optionally lets a vertical sheet stretch a short distance below its lowest (largest-top) detent. Resistance increases with finger travel, then a native spring returns the sheet to that same detent on release or cancellation. The return emits releaseAction: 'bounce' through the existing release/detent events. Followers move with the sheet and detent progress remains clamped to its configured ranges.
sheet.draggable.setConfig('collapsedBounce', {
enabled: true,
maxDistance: 48,
resistance: 0.35,
duration: 0.32,
damping: 0.8
});enabled(Boolean, defaultfalse) — Enables resistance and spring-back below the collapsed boundary. Requires configured detents.maxDistance(Number, default48) — Maximum elastic travel in points; the sheet approaches this limit as the user pulls farther.resistance(Number, default0.35, range0.01–1) — Initial fraction of finger movement applied to the sheet. Smaller values feel firmer; movement progressively decreases beyond that initial fraction.duration(Number, default0.32) — Return spring duration in seconds.damping(Number, default0.8, range0.01–1) — Return spring damping ratio.
The option works with scrollEnabledByDetent and suppressScrollMomentum. It is ignored while scrollHandoff.atTopBehavior is 'dismiss'. Other drag boundaries retain their existing constraints. Disable it at runtime with sheet.draggable.setConfig('collapsedBounce.enabled', false).
progressRanges accepts multiple named ranges. Each item requires a unique id plus from and to values that reference detent names or numeric sheet-top positions.
sheet.addEventListener('detentprogress', function (event) {
if (event.id === 'middleToExpanded') {
detailsView.opacity = event.progress;
}
});For each range, progress is clamped from 0 at from to 1 at to. It returns from 1 to 0 when the sheet moves in the opposite direction. The event also includes id, from, to, fromTop, toTop, top, and interactive.
Progress starts with the user's drag and continues from the sheet's visible presentation position during the native release animation. The destination is finalized at exactly 0 or 1. interactive is true while the finger is moving the sheet and false while the native animation is settling it.
Programmatic progress is opt-in through setDetent() options:
updateProgress(Boolean, defaultfalse) — Emitsdetentprogresswhile moving to the requested detent.- With
animated: true, progress follows the visible native animation and finishes at the exact destination value. - With
animated: false, one exact destination update is emitted.
Initial detent placement does not emit progress. Calling setDetent() without updateProgress: true retains the existing behavior and emits no programmatic progress.
scrollHandoff.view is the descendant TableView, ListView, or ScrollView to coordinate. atTopBehavior may be changed at runtime:
sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'scroll');
sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'drag');
sheet.draggable.setConfig('scrollHandoff.atTopBehavior', 'dismiss');
sheet.draggable.setConfig('scrollHandoff.suppressScrollMomentum', true);drag(default) — A downward pull transfers from the inner content to the sheet when the content reaches its adjusted top offset.scroll— The inner view retains downward pulls while the sheet is expanded, including its normal edge behavior.dismiss— Uses the same native handoff asdrag, then targetsdismissDetentand emitsdismisswhen the release passesdismissThresholdordetentVelocityThreshold.top(Number) — Optional expanded sheet position used for handoff when no detents are configured. Otherwise the smallest detent orminTopis used.topTolerance(Number, default1) — Content and sheet top-edge tolerance in points.suppressScrollMomentum(Boolean, defaultfalse) — When an upward gesture that began inside the scrolling view is owned by the sheet and targets a higher detent, cancels the scrolling view's residual flick momentum and keeps its content at the adjusted top offset. Normal scrolling and deceleration remain unchanged when the scrolling view owns the gesture.scrollEnabledByDetent(Object, optional) — Maps detent names to scrolling booleans. Afalseentry disables native scrolling and pins the content to its current adjusted top, including during a drag and release from that detent. Scrolling stays disabled until the destination settles; moving into a disabled detent locks it as settling begins. Atrueentry enables scrolling subject to the normal sheet handoff rules. Omitted names use the scrolling state captured before this policy took control.dismissThreshold(Number, default120) — Downward distance required for thedismisspolicy.dismissDetent(String) — Named dismissal target. Defaults to the largest configured detent.
With suppression enabled, the adjusted top is recalculated throughout the sheet's release animation and after final layout. This preserves UIKit's navigation-bar and safe-area positioning of the first row while the sheet continues expanding beneath the bars.
For example, scrollEnabledByDetent: { collapsed: false, middle: true, expanded: true } keeps the table at its adjusted top while collapsed and throughout the transition out of collapsed. The destination's setting takes effect before detentchange fires. Update entries at runtime with sheet.draggable.setConfig('scrollHandoff.scrollEnabledByDetent.collapsed', false). Remove the policy with sheet.draggable.setConfig('scrollHandoff.scrollEnabledByDetent', null) to restore the original native scrolling state; removing the handoff or gesture also restores it.
The module does not remove the sheet automatically. Handle the dismiss event to close, hide, or recycle it after the native motion completes.
Size the sheet so its bottom edge meets the window bottom at the expanded detent (height: screenHeight - expandedTop). Extra offscreen height also enlarges the native scroll view's viewport and can leave its final rows below the visible window.
followers keeps sibling controls visually attached to the sheet without JavaScript move events. This is useful for map buttons or other controls that should travel with a collapsed sheet, clamp at a middle detent, and fade as the sheet expands.
view(Ti.UI.View, required) — A sibling of the draggable sheet.attachUntil(StringorNumber) — Detent name or sheet top where the follower stops moving upward.offset(Number, default-12) — Vertical offset from the sheet top to the follower's bottom edge. A negative value creates a gap above the sheet.gap(Number) — Positive shorthand for a gap above the sheet; overridesoffset.fadeBetween(Array) — Two detent names or numeric tops: fully visible first, fully hidden second.visibleAlpha/hiddenAlpha(Number, defaults1/0) — Alpha endpoints.bringToFront(Boolean, defaulttrue) — Keeps the follower above the sheet so its detent fade remains visible. Set tofalsewhen the application manages sibling z-order itself.passThroughTouches(Boolean, defaultfalse) — Passes touches on the follower's root view to underlying content while preserving normal touch handling for every child and nested descendant.disableTouchesWhenHidden(Boolean, defaulttrue) — Disables native hit testing at the hidden endpoint and restores the view's original interaction state when visible.
The sheet emits these lifecycle events:
handoff— Gesture ownership changes;ownerisscrollordraggable.detentprogress— Clamped0through1progress for each configured range whose value changed, including native settling after release.detentwillchange— A native detent animation is about to begin.detentchange— The native detent animation completed; includesdetentandtop.dismiss— Adismisspolicy release completed at its dismissal detent.
Set nativeReleaseAnimation to true to let the native pan recognizer decide and begin the horizontal release animation immediately. This avoids waiting for an end event to cross the JavaScript bridge before starting the swipe or snapback animation.
var card = Draggable.createView({
draggableConfig: {
axis: 'xy',
nativeReleaseAnimation: true,
swipeThreshold: 80,
swipeVelocityThreshold: 650,
swipeOutDistance: Ti.Platform.displayCaps.platformWidth + 100,
swipeOutDuration: 0.25,
snapBack: true,
snapBackDuration: 0.42,
snapBackDamping: 0.84
}
});The native release path applies only to horizontal releases. With axis: 'xy', vertical releases continue through the existing end event so the application can handle its own vertical behavior.
nativeReleaseAnimation(Boolean, defaultfalse) — Enables the native horizontal release path.swipeThreshold(Number, default80) — Horizontal distance in points required to dismiss. Set to0to disable the distance threshold.swipeVelocityThreshold(Number, default650) — Horizontal release velocity in points per second required to dismiss. Set to0to disable the velocity threshold.swipeOutDistance(Number) — Horizontal distance from the gesture's starting center to the offscreen target. The default is the parent width plus the draggable view width.swipeOutDuration(Number, default0.25) — Swipe completion duration in seconds.snapBack(Boolean, defaulttrue) — Returns a horizontal release that misses both thresholds to its starting position.snapBackDuration(Number, default0.42) — Snapback duration in seconds.snapBackDamping(Number, default0.84) — Snapback spring damping ratio from0.01through1.0.
The existing end event still fires. Its payload includes nativeReleaseHandled and, when handled, releaseAction (swipe or snapback). The module also emits:
release— Fires immediately after the native release animation starts.swipe— Fires when a native offscreen swipe finishes and includesdirection(leftorright).snapback— Fires when the native return animation finishes.
The left-most boundary of the view being dragged. Can be set to null to disable property.
The right-most boundary of the view being dragged. Can be set to null to disable property.
The top-most boundary of the view being dragged. Can be set to null to disable property.
The bottom-most boundary of the view being dragged. Can be set to null to disable property.
Ensure that that the right edge of the view being dragged keeps its integrity. Can be set to null to disable property.
Ensure that that the bottom edge of the view being dragged keeps its integrity. Can be set to null to disable property.
An array of views that should be translated along with the view being dragged. See View Mapping.
In the case where you want multiple views to be translated at the same time you can pass the maps property to the draggable config. This functionality is useful for creating parallax or 1:1 movements.
The maps property accepts an array of objects containing any of the following. The view property is required.
The view to translate.
A positive or negative number. Numbers less than |1| such as 0.1, 0.2, or 0.3 will cause the translation to move faster then the translation. A parallaxAmount of 1 will translate mapped views 1:1. A parallaxAmount > 1 will result in a slower translation.
An object containing the boundaries of the mapped view. Can have the following:
- x
- start The start position for the mapped view.
- end The end position for the mapped view.
- callback A function that will receive the completed percentage of the mapped translation. . Android does not support this option.
- fromCenter Translate the view from its center. Android does not support this option.
- y
- start The start position for the mapped view.
- end The end position for the mapped view.
- callback A function that will receive the completed percentage of the mapped translation. . Android does not support this option.
- fromCenter Translate the view from its center. Android does not support this option.
The work is largely based on Pedro Enrique's TiDraggable module license under the MIT (V2) license.