[Summary view] [Print] [Text view]

   1  
   2  <ul class="UIAPIPlugin-toc">
   3  <li><a href="#overview">Overview</a></li>
   4  <li><a href="#options">Options</a></li>
   5  <li><a href="#events">Events</a></li>
   6  <li><a href="#methods">Methods</a></li>
   7  <li><a href="#theming">Theming</a></li>
   8  </ul>
   9  <div class="UIAPIPlugin">
  10    <h1>jQuery UI Draggable</h1>
  11    <div id="overview">
  12      <h2 class="top-header">Overview</h2>
  13      <div id="overview-main">
  14          <p>The jQuery UI Draggable plugin makes selected elements draggable by mouse.</p>
  15  <p>Draggable elements gets a class of <code>ui-draggable</code>. During drag the element also gets a class of <code>ui-draggable-dragging</code>. If you want not just drag, but drag-and-drop, see the jQuery UI Droppable plugin, which provides a drop target for draggables.</p>
  16  <p>All callbacks (start, stop, drag) receive two arguments: The original browser event and a prepared ui object, view below for a documentation of this object (if you name your second argument 'ui'):</p>
  17  <ul>
  18  <li><b>ui.helper</b> - the jQuery object representing the helper that's being dragged</li>
  19  <li><b>ui.position</b> - current position of the helper as { top, left } object, relative to the offset element</li>
  20  <li><b>ui.offset</b> - current absolute position of the helper as { top, left } object, relative to page</li>
  21  </ul>
  22      </div>
  23      <div id="overview-dependencies">
  24          <h3>Dependencies</h3>
  25          <ul>
  26  <li>UI Core</li>
  27  </ul>
  28      </div>
  29      <div id="overview-example">
  30          <h3>Example</h3>
  31          <div id="overview-example" class="example">
  32  <ul><li><a href="#demo"><span>Demo</span></a></li><li><a href="#source"><span>View Source</span></a></li></ul>
  33  <p><div id="demo" class="tabs-container" rel="170">
  34  Initialize a draggable with default options.<br />
  35  </p>
  36  <pre>$(&quot;#draggable&quot;).draggable();
  37  </pre>
  38  <p></div><div id="source" class="tabs-container">
  39  </p>
  40  <pre>&lt;!DOCTYPE html&gt;
  41  &lt;html&gt;
  42  &lt;head&gt;
  43    &lt;link type=&quot;text/css&quot; href=&quot;http://jqueryui.com/latest/themes/base/ui.all.css&quot; rel=&quot;stylesheet&quot; /&gt;
  44    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/jquery-1.3.2.js&quot;&gt;&lt;/script&gt;
  45    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/ui.core.js&quot;&gt;&lt;/script&gt;
  46    &lt;script type=&quot;text/javascript&quot; src=&quot;http://jqueryui.com/latest/ui/ui.draggable.js&quot;&gt;&lt;/script&gt;
  47    &lt;style type=&quot;text/css&quot;&gt;
  48      #draggable { width: 100px; height: 70px; background: silver; }
  49    &lt;/style&gt;
  50    &lt;script type="text/javascript"&gt;
  51    $(document).ready(function(){
  52      $(&quot;#draggable&quot;).draggable();
  53    });
  54    &lt;/script&gt;
  55  &lt;/head&gt;
  56  &lt;body style="font-size:62.5%;"&gt;
  57    
  58  &lt;div id=&quot;draggable&quot;&gt;Drag me&lt;/div&gt;
  59  
  60  &lt;/body&gt;
  61  &lt;/html&gt;
  62  </pre>
  63  <p></div>
  64  </p><p></div>
  65      </div>
  66    </div>
  67    <div id="options">
  68      <h2 class="top-header">Options</h2>
  69      <ul class="options-list">
  70        
  71  <li class="option" id="option-addClasses">
  72    <div class="option-header">
  73      <h3 class="option-name"><a href="#option-addClasses">addClasses</a></h3>
  74      <dl>
  75        <dt class="option-type-label">Type:</dt>
  76          <dd class="option-type">Boolean</dd>
  77        
  78        <dt class="option-default-label">Default:</dt>
  79          <dd class="option-default">true</dd>
  80        
  81      </dl>
  82    </div>
  83    <div class="option-description">
  84      <p>If set to false, will prevent the <code>ui-draggable</code> class from being added. This may be desired as a performance optimization when calling <code>.draggable()</code> init on many hundreds of elements.</p>
  85    </div>
  86    <div class="option-examples">
  87      <h4>Code examples</h4>
  88      <dl class="option-examples-list">
  89      
  90  <dt>
  91    Initialize a draggable with the <code>addClasses</code> option specified.
  92  </dt>
  93  <dd>
  94  <pre><code>$('.selector').draggable({ addClasses: false });</code></pre>
  95  </dd>
  96  
  97      
  98  <dt>
  99    Get or set the <code>addClasses</code> option, after init.
 100  </dt>
 101  <dd>
 102  <pre><code>//getter
 103  var addClasses = $('.selector').draggable('option', 'addClasses');
 104  //setter
 105  $('.selector').draggable('option', 'addClasses', false);</code></pre>
 106  </dd>
 107  
 108      </dl>
 109    </div>
 110  </li>
 111  
 112  
 113  <li class="option" id="option-appendTo">
 114    <div class="option-header">
 115      <h3 class="option-name"><a href="#option-appendTo">appendTo</a></h3>
 116      <dl>
 117        <dt class="option-type-label">Type:</dt>
 118          <dd class="option-type">Element, Selector</dd>
 119        
 120        <dt class="option-default-label">Default:</dt>
 121          <dd class="option-default">'parent'</dd>
 122        
 123      </dl>
 124    </div>
 125    <div class="option-description">
 126      <p>The element passed to or selected by the <code>appendTo</code> option will be used as the draggable helper's container during dragging. By default, the helper is appended to the same container as the draggable.</p>
 127    </div>
 128    <div class="option-examples">
 129      <h4>Code examples</h4>
 130      <dl class="option-examples-list">
 131      
 132  <dt>
 133    Initialize a draggable with the <code>appendTo</code> option specified.
 134  </dt>
 135  <dd>
 136  <pre><code>$('.selector').draggable({ appendTo: 'body' });</code></pre>
 137  </dd>
 138  
 139      
 140  <dt>
 141    Get or set the <code>appendTo</code> option, after init.
 142  </dt>
 143  <dd>
 144  <pre><code>//getter
 145  var appendTo = $('.selector').draggable('option', 'appendTo');
 146  //setter
 147  $('.selector').draggable('option', 'appendTo', 'body');</code></pre>
 148  </dd>
 149  
 150      </dl>
 151    </div>
 152  </li>
 153  
 154  
 155  <li class="option" id="option-axis">
 156    <div class="option-header">
 157      <h3 class="option-name"><a href="#option-axis">axis</a></h3>
 158      <dl>
 159        <dt class="option-type-label">Type:</dt>
 160          <dd class="option-type">String</dd>
 161        
 162        <dt class="option-default-label">Default:</dt>
 163          <dd class="option-default">false</dd>
 164        
 165      </dl>
 166    </div>
 167    <div class="option-description">
 168      <p>Constrains dragging to either the horizontal (x) or vertical (y) axis. Possible values: 'x', 'y'.</p>
 169    </div>
 170    <div class="option-examples">
 171      <h4>Code examples</h4>
 172      <dl class="option-examples-list">
 173      
 174  <dt>
 175    Initialize a draggable with the <code>axis</code> option specified.
 176  </dt>
 177  <dd>
 178  <pre><code>$('.selector').draggable({ axis: 'x' });</code></pre>
 179  </dd>
 180  
 181      
 182  <dt>
 183    Get or set the <code>axis</code> option, after init.
 184  </dt>
 185  <dd>
 186  <pre><code>//getter
 187  var axis = $('.selector').draggable('option', 'axis');
 188  //setter
 189  $('.selector').draggable('option', 'axis', 'x');</code></pre>
 190  </dd>
 191  
 192      </dl>
 193    </div>
 194  </li>
 195  
 196  
 197  <li class="option" id="option-cancel">
 198    <div class="option-header">
 199      <h3 class="option-name"><a href="#option-cancel">cancel</a></h3>
 200      <dl>
 201        <dt class="option-type-label">Type:</dt>
 202          <dd class="option-type">Selector</dd>
 203        
 204        <dt class="option-default-label">Default:</dt>
 205          <dd class="option-default">':input,option'</dd>
 206        
 207      </dl>
 208    </div>
 209    <div class="option-description">
 210      <p>Prevents dragging from starting on specified elements.</p>
 211    </div>
 212    <div class="option-examples">
 213      <h4>Code examples</h4>
 214      <dl class="option-examples-list">
 215      
 216  <dt>
 217    Initialize a draggable with the <code>cancel</code> option specified.
 218  </dt>
 219  <dd>
 220  <pre><code>$('.selector').draggable({ cancel: 'button' });</code></pre>
 221  </dd>
 222  
 223      
 224  <dt>
 225    Get or set the <code>cancel</code> option, after init.
 226  </dt>
 227  <dd>
 228  <pre><code>//getter
 229  var cancel = $('.selector').draggable('option', 'cancel');
 230  //setter
 231  $('.selector').draggable('option', 'cancel', 'button');</code></pre>
 232  </dd>
 233  
 234      </dl>
 235    </div>
 236  </li>
 237  
 238  
 239  <li class="option" id="option-connectToSortable">
 240    <div class="option-header">
 241      <h3 class="option-name"><a href="#option-connectToSortable">connectToSortable</a></h3>
 242      <dl>
 243        <dt class="option-type-label">Type:</dt>
 244          <dd class="option-type">Selector</dd>
 245        
 246        <dt class="option-default-label">Default:</dt>
 247          <dd class="option-default">false</dd>
 248        
 249      </dl>
 250    </div>
 251    <div class="option-description">
 252      <p>Allows the draggable to be dropped onto the specified sortables. If this option is used (<code>helper</code> must be set to 'clone' in order to work flawlessly), a draggable can be dropped onto a sortable list and then becomes part of it.
 253  </p><p>Note: Specifying this option as an array of selectors has been removed.</p>
 254    </div>
 255    <div class="option-examples">
 256      <h4>Code examples</h4>
 257      <dl class="option-examples-list">
 258      
 259  <dt>
 260    Initialize a draggable with the <code>connectToSortable</code> option specified.
 261  </dt>
 262  <dd>
 263  <pre><code>$('.selector').draggable({ connectToSortable: 'ul#myList' });</code></pre>
 264  </dd>
 265  
 266      
 267  <dt>
 268    Get or set the <code>connectToSortable</code> option, after init.
 269  </dt>
 270  <dd>
 271  <pre><code>//getter
 272  var connectToSortable = $('.selector').draggable('option', 'connectToSortable');
 273  //setter
 274  $('.selector').draggable('option', 'connectToSortable', 'ul#myList');</code></pre>
 275  </dd>
 276  
 277      </dl>
 278    </div>
 279  </li>
 280  
 281  
 282  <li class="option" id="option-containment">
 283    <div class="option-header">
 284      <h3 class="option-name"><a href="#option-containment">containment</a></h3>
 285      <dl>
 286        <dt class="option-type-label">Type:</dt>
 287          <dd class="option-type">Selector, Element, String, Array</dd>
 288        
 289        <dt class="option-default-label">Default:</dt>
 290          <dd class="option-default">false</dd>
 291        
 292      </dl>
 293    </div>
 294    <div class="option-description">
 295      <p>Constrains dragging to within the bounds of the specified element or region. Possible string values: 'parent', 'document', 'window', [x1, y1, x2, y2].</p>
 296    </div>
 297    <div class="option-examples">
 298      <h4>Code examples</h4>
 299      <dl class="option-examples-list">
 300      
 301  <dt>
 302    Initialize a draggable with the <code>containment</code> option specified.
 303  </dt>
 304  <dd>
 305  <pre><code>$('.selector').draggable({ containment: 'parent' });</code></pre>
 306  </dd>
 307  
 308      
 309  <dt>
 310    Get or set the <code>containment</code> option, after init.
 311  </dt>
 312  <dd>
 313  <pre><code>//getter
 314  var containment = $('.selector').draggable('option', 'containment');
 315  //setter
 316  $('.selector').draggable('option', 'containment', 'parent');</code></pre>
 317  </dd>
 318  
 319      </dl>
 320    </div>
 321  </li>
 322  
 323  
 324  <li class="option" id="option-cursor">
 325    <div class="option-header">
 326      <h3 class="option-name"><a href="#option-cursor">cursor</a></h3>
 327      <dl>
 328        <dt class="option-type-label">Type:</dt>
 329          <dd class="option-type">String</dd>
 330        
 331        <dt class="option-default-label">Default:</dt>
 332          <dd class="option-default">'auto'</dd>
 333        
 334      </dl>
 335    </div>
 336    <div class="option-description">
 337      <p>The css cursor during the drag operation.</p>
 338    </div>
 339    <div class="option-examples">
 340      <h4>Code examples</h4>
 341      <dl class="option-examples-list">
 342      
 343  <dt>
 344    Initialize a draggable with the <code>cursor</code> option specified.
 345  </dt>
 346  <dd>
 347  <pre><code>$('.selector').draggable({ cursor: 'crosshair' });</code></pre>
 348  </dd>
 349  
 350      
 351  <dt>
 352    Get or set the <code>cursor</code> option, after init.
 353  </dt>
 354  <dd>
 355  <pre><code>//getter
 356  var cursor = $('.selector').draggable('option', 'cursor');
 357  //setter
 358  $('.selector').draggable('option', 'cursor', 'crosshair');</code></pre>
 359  </dd>
 360  
 361      </dl>
 362    </div>
 363  </li>
 364  
 365  
 366  <li class="option" id="option-cursorAt">
 367    <div class="option-header">
 368      <h3 class="option-name"><a href="#option-cursorAt">cursorAt</a></h3>
 369      <dl>
 370        <dt class="option-type-label">Type:</dt>
 371          <dd class="option-type">Object</dd>
 372        
 373        <dt class="option-default-label">Default:</dt>
 374          <dd class="option-default">false</dd>
 375        
 376      </dl>
 377    </div>
 378    <div class="option-description">
 379      <p>Moves the dragging helper so the cursor always appears to drag from the same position. Coordinates can be given as a hash using a combination of one or two keys: <code>{ top, left, right, bottom }</code>.</p>
 380    </div>
 381    <div class="option-examples">
 382      <h4>Code examples</h4>
 383      <dl class="option-examples-list">
 384      
 385  <dt>
 386    Initialize a draggable with the <code>cursorAt</code> option specified.
 387  </dt>
 388  <dd>
 389  <pre><code>$('.selector').draggable({ cursorAt: { left: 5 } });</code></pre>
 390  </dd>
 391  
 392      
 393  <dt>
 394    Get or set the <code>cursorAt</code> option, after init.
 395  </dt>
 396  <dd>
 397  <pre><code>//getter
 398  var cursorAt = $('.selector').draggable('option', 'cursorAt');
 399  //setter
 400  $('.selector').draggable('option', 'cursorAt', { left: 5 });</code></pre>
 401  </dd>
 402  
 403      </dl>
 404    </div>
 405  </li>
 406  
 407  
 408  <li class="option" id="option-delay">
 409    <div class="option-header">
 410      <h3 class="option-name"><a href="#option-delay">delay</a></h3>
 411      <dl>
 412        <dt class="option-type-label">Type:</dt>
 413          <dd class="option-type">Integer</dd>
 414        
 415        <dt class="option-default-label">Default:</dt>
 416          <dd class="option-default">0</dd>
 417        
 418      </dl>
 419    </div>
 420    <div class="option-description">
 421      <p>Time in milliseconds after mousedown until dragging should start. This option can be used to prevent unwanted drags when clicking on an element.</p>
 422    </div>
 423    <div class="option-examples">
 424      <h4>Code examples</h4>
 425      <dl class="option-examples-list">
 426      
 427  <dt>
 428    Initialize a draggable with the <code>delay</code> option specified.
 429  </dt>
 430  <dd>
 431  <pre><code>$('.selector').draggable({ delay: 500 });</code></pre>
 432  </dd>
 433  
 434      
 435  <dt>
 436    Get or set the <code>delay</code> option, after init.
 437  </dt>
 438  <dd>
 439  <pre><code>//getter
 440  var delay = $('.selector').draggable('option', 'delay');
 441  //setter
 442  $('.selector').draggable('option', 'delay', 500);</code></pre>
 443  </dd>
 444  
 445      </dl>
 446    </div>
 447  </li>
 448  
 449  
 450  <li class="option" id="option-distance">
 451    <div class="option-header">
 452      <h3 class="option-name"><a href="#option-distance">distance</a></h3>
 453      <dl>
 454        <dt class="option-type-label">Type:</dt>
 455          <dd class="option-type">Integer</dd>
 456        
 457        <dt class="option-default-label">Default:</dt>
 458          <dd class="option-default">1</dd>
 459        
 460      </dl>
 461    </div>
 462    <div class="option-description">
 463      <p>Distance in pixels after mousedown the mouse must move before dragging should start. This option can be used to prevent unwanted drags when clicking on an element.</p>
 464    </div>
 465    <div class="option-examples">
 466      <h4>Code examples</h4>
 467      <dl class="option-examples-list">
 468      
 469  <dt>
 470    Initialize a draggable with the <code>distance</code> option specified.
 471  </dt>
 472  <dd>
 473  <pre><code>$('.selector').draggable({ distance: 30 });</code></pre>
 474  </dd>
 475  
 476      
 477  <dt>
 478    Get or set the <code>distance</code> option, after init.
 479  </dt>
 480  <dd>
 481  <pre><code>//getter
 482  var distance = $('.selector').draggable('option', 'distance');
 483  //setter
 484  $('.selector').draggable('option', 'distance', 30);</code></pre>
 485  </dd>
 486  
 487      </dl>
 488    </div>
 489  </li>
 490  
 491  
 492  <li class="option" id="option-grid">
 493    <div class="option-header">
 494      <h3 class="option-name"><a href="#option-grid">grid</a></h3>
 495      <dl>
 496        <dt class="option-type-label">Type:</dt>
 497          <dd class="option-type">Array</dd>
 498        
 499        <dt class="option-default-label">Default:</dt>
 500          <dd class="option-default">false</dd>
 501        
 502      </dl>
 503    </div>
 504    <div class="option-description">
 505      <p>Snaps the dragging helper to a grid, every x and y pixels. Array values: [x, y]</p>
 506    </div>
 507    <div class="option-examples">
 508      <h4>Code examples</h4>
 509      <dl class="option-examples-list">
 510      
 511  <dt>
 512    Initialize a draggable with the <code>grid</code> option specified.
 513  </dt>
 514  <dd>
 515  <pre><code>$('.selector').draggable({ grid: [50, 20] });</code></pre>
 516  </dd>
 517  
 518      
 519  <dt>
 520    Get or set the <code>grid</code> option, after init.
 521  </dt>
 522  <dd>
 523  <pre><code>//getter
 524  var grid = $('.selector').draggable('option', 'grid');
 525  //setter
 526  $('.selector').draggable('option', 'grid', [50, 20]);</code></pre>
 527  </dd>
 528  
 529      </dl>
 530    </div>
 531  </li>
 532  
 533  
 534  <li class="option" id="option-handle">
 535    <div class="option-header">
 536      <h3 class="option-name"><a href="#option-handle">handle</a></h3>
 537      <dl>
 538        <dt class="option-type-label">Type:</dt>
 539          <dd class="option-type">Element, Selector</dd>
 540        
 541        <dt class="option-default-label">Default:</dt>
 542          <dd class="option-default">false</dd>
 543        
 544      </dl>
 545    </div>
 546    <div class="option-description">
 547      <p>If specified, restricts drag start click to the specified element(s).</p>
 548    </div>
 549    <div class="option-examples">
 550      <h4>Code examples</h4>
 551      <dl class="option-examples-list">
 552      
 553  <dt>
 554    Initialize a draggable with the <code>handle</code> option specified.
 555  </dt>
 556  <dd>
 557  <pre><code>$('.selector').draggable({ handle: 'h2' });</code></pre>
 558  </dd>
 559  
 560      
 561  <dt>
 562    Get or set the <code>handle</code> option, after init.
 563  </dt>
 564  <dd>
 565  <pre><code>//getter
 566  var handle = $('.selector').draggable('option', 'handle');
 567  //setter
 568  $('.selector').draggable('option', 'handle', 'h2');</code></pre>
 569  </dd>
 570  
 571      </dl>
 572    </div>
 573  </li>
 574  
 575  
 576  <li class="option" id="option-helper">
 577    <div class="option-header">
 578      <h3 class="option-name"><a href="#option-helper">helper</a></h3>
 579      <dl>
 580        <dt class="option-type-label">Type:</dt>
 581          <dd class="option-type">String, Function</dd>
 582        
 583        <dt class="option-default-label">Default:</dt>
 584          <dd class="option-default">'original'</dd>
 585        
 586      </dl>
 587    </div>
 588    <div class="option-description">
 589      <p>Allows for a helper element to be used for dragging display. Possible values: 'original', 'clone', Function. If a function is specified, it must return a DOMElement.</p>
 590    </div>
 591    <div class="option-examples">
 592      <h4>Code examples</h4>
 593      <dl class="option-examples-list">
 594      
 595  <dt>
 596    Initialize a draggable with the <code>helper</code> option specified.
 597  </dt>
 598  <dd>
 599  <pre><code>$('.selector').draggable({ helper: 'clone' });</code></pre>
 600  </dd>
 601  
 602      
 603  <dt>
 604    Get or set the <code>helper</code> option, after init.
 605  </dt>
 606  <dd>
 607  <pre><code>//getter
 608  var helper = $('.selector').draggable('option', 'helper');
 609  //setter
 610  $('.selector').draggable('option', 'helper', 'clone');</code></pre>
 611  </dd>
 612  
 613      </dl>
 614    </div>
 615  </li>
 616  
 617  
 618  <li class="option" id="option-iframeFix">
 619    <div class="option-header">
 620      <h3 class="option-name"><a href="#option-iframeFix">iframeFix</a></h3>
 621      <dl>
 622        <dt class="option-type-label">Type:</dt>
 623          <dd class="option-type">Boolean, Selector</dd>
 624        
 625        <dt class="option-default-label">Default:</dt>
 626          <dd class="option-default">false</dd>
 627        
 628      </dl>
 629    </div>
 630    <div class="option-description">
 631      <p>Prevent iframes from capturing the mousemove events during a drag. Useful in combination with cursorAt, or in any case, if the mouse cursor is not over the helper. If set to true, transparent overlays will be placed over all iframes on the page. If a selector is supplied, the matched iframes will have an overlay placed over them.</p>
 632    </div>
 633    <div class="option-examples">
 634      <h4>Code examples</h4>
 635      <dl class="option-examples-list">
 636      
 637  <dt>
 638    Initialize a draggable with the <code>iframeFix</code> option specified.
 639  </dt>
 640  <dd>
 641  <pre><code>$('.selector').draggable({ iframeFix: true });</code></pre>
 642  </dd>
 643  
 644      
 645  <dt>
 646    Get or set the <code>iframeFix</code> option, after init.
 647  </dt>
 648  <dd>
 649  <pre><code>//getter
 650  var iframeFix = $('.selector').draggable('option', 'iframeFix');
 651  //setter
 652  $('.selector').draggable('option', 'iframeFix', true);</code></pre>
 653  </dd>
 654  
 655      </dl>
 656    </div>
 657  </li>
 658  
 659  
 660  <li class="option" id="option-opacity">
 661    <div class="option-header">
 662      <h3 class="option-name"><a href="#option-opacity">opacity</a></h3>
 663      <dl>
 664        <dt class="option-type-label">Type:</dt>
 665          <dd class="option-type">Float</dd>
 666        
 667        <dt class="option-default-label">Default:</dt>
 668          <dd class="option-default">false</dd>
 669        
 670      </dl>
 671    </div>
 672    <div class="option-description">
 673      <p>Opacity for the helper while being dragged.</p>
 674    </div>
 675    <div class="option-examples">
 676      <h4>Code examples</h4>
 677      <dl class="option-examples-list">
 678      
 679  <dt>
 680    Initialize a draggable with the <code>opacity</code> option specified.
 681  </dt>
 682  <dd>
 683  <pre><code>$('.selector').draggable({ opacity: 0.35 });</code></pre>
 684  </dd>
 685  
 686      
 687  <dt>
 688    Get or set the <code>opacity</code> option, after init.
 689  </dt>
 690  <dd>
 691  <pre><code>//getter
 692  var opacity = $('.selector').draggable('option', 'opacity');
 693  //setter
 694  $('.selector').draggable('option', 'opacity', 0.35);</code></pre>
 695  </dd>
 696  
 697      </dl>
 698    </div>
 699  </li>
 700  
 701  
 702  <li class="option" id="option-refreshPositions">
 703    <div class="option-header">
 704      <h3 class="option-name"><a href="#option-refreshPositions">refreshPositions</a></h3>
 705      <dl>
 706        <dt class="option-type-label">Type:</dt>
 707          <dd class="option-type">Boolean</dd>
 708        
 709        <dt class="option-default-label">Default:</dt>
 710          <dd class="option-default">false</dd>
 711        
 712      </dl>
 713    </div>
 714    <div class="option-description">
 715      <p>If set to true, all droppable positions are calculated on every mousemove. Caution: This solves issues on highly dynamic pages, but dramatically decreases performance.</p>
 716    </div>
 717    <div class="option-examples">
 718      <h4>Code examples</h4>
 719      <dl class="option-examples-list">
 720      
 721  <dt>
 722    Initialize a draggable with the <code>refreshPositions</code> option specified.
 723  </dt>
 724  <dd>
 725  <pre><code>$('.selector').draggable({ refreshPositions: true });</code></pre>
 726  </dd>
 727  
 728      
 729  <dt>
 730    Get or set the <code>refreshPositions</code> option, after init.
 731  </dt>
 732  <dd>
 733  <pre><code>//getter
 734  var refreshPositions = $('.selector').draggable('option', 'refreshPositions');
 735  //setter
 736  $('.selector').draggable('option', 'refreshPositions', true);</code></pre>
 737  </dd>
 738  
 739      </dl>
 740    </div>
 741  </li>
 742  
 743  
 744  <li class="option" id="option-revert">
 745    <div class="option-header">
 746      <h3 class="option-name"><a href="#option-revert">revert</a></h3>
 747      <dl>
 748        <dt class="option-type-label">Type:</dt>
 749          <dd class="option-type">Boolean, String</dd>
 750        
 751        <dt class="option-default-label">Default:</dt>
 752          <dd class="option-default">false</dd>
 753        
 754      </dl>
 755    </div>
 756    <div class="option-description">
 757      <p>If set to true, the element will return to its start position when dragging stops. Possible string values: 'valid', 'invalid'. If set to invalid, revert will only occur if the draggable has not been dropped on a droppable. For valid, it's the other way around.</p>
 758    </div>
 759    <div class="option-examples">
 760      <h4>Code examples</h4>
 761      <dl class="option-examples-list">
 762      
 763  <dt>
 764    Initialize a draggable with the <code>revert</code> option specified.
 765  </dt>
 766  <dd>
 767  <pre><code>$('.selector').draggable({ revert: true });</code></pre>
 768  </dd>
 769  
 770      
 771  <dt>
 772    Get or set the <code>revert</code> option, after init.
 773  </dt>
 774  <dd>
 775  <pre><code>//getter
 776  var revert = $('.selector').draggable('option', 'revert');
 777  //setter
 778  $('.selector').draggable('option', 'revert', true);</code></pre>
 779  </dd>
 780  
 781      </dl>
 782    </div>
 783  </li>
 784  
 785  
 786  <li class="option" id="option-revertDuration">
 787    <div class="option-header">
 788      <h3 class="option-name"><a href="#option-revertDuration">revertDuration</a></h3>
 789      <dl>
 790        <dt class="option-type-label">Type:</dt>
 791          <dd class="option-type">Integer</dd>
 792        
 793        <dt class="option-default-label">Default:</dt>
 794          <dd class="option-default">500</dd>
 795        
 796      </dl>
 797    </div>
 798    <div class="option-description">
 799      <p>The duration of the revert animation, in milliseconds. Ignored if revert is false.</p>
 800    </div>
 801    <div class="option-examples">
 802      <h4>Code examples</h4>
 803      <dl class="option-examples-list">
 804      
 805  <dt>
 806    Initialize a draggable with the <code>revertDuration</code> option specified.
 807  </dt>
 808  <dd>
 809  <pre><code>$('.selector').draggable({ revertDuration: 1000 });</code></pre>
 810  </dd>
 811  
 812      
 813  <dt>
 814    Get or set the <code>revertDuration</code> option, after init.
 815  </dt>
 816  <dd>
 817  <pre><code>//getter
 818  var revertDuration = $('.selector').draggable('option', 'revertDuration');
 819  //setter
 820  $('.selector').draggable('option', 'revertDuration', 1000);</code></pre>
 821  </dd>
 822  
 823      </dl>
 824    </div>
 825  </li>
 826  
 827  
 828  <li class="option" id="option-scope">
 829    <div class="option-header">
 830      <h3 class="option-name"><a href="#option-scope">scope</a></h3>
 831      <dl>
 832        <dt class="option-type-label">Type:</dt>
 833          <dd class="option-type">String</dd>
 834        
 835        <dt class="option-default-label">Default:</dt>
 836          <dd class="option-default">'default'</dd>
 837        
 838      </dl>
 839    </div>
 840    <div class="option-description">
 841      <p>Used to group sets of draggable and droppable items, in addition to droppable's accept option. A draggable with the same scope value as a droppable will be accepted by the droppable.</p>
 842    </div>
 843    <div class="option-examples">
 844      <h4>Code examples</h4>
 845      <dl class="option-examples-list">
 846      
 847  <dt>
 848    Initialize a draggable with the <code>scope</code> option specified.
 849  </dt>
 850  <dd>
 851  <pre><code>$('.selector').draggable({ scope: 'tasks' });</code></pre>
 852  </dd>
 853  
 854      
 855  <dt>
 856    Get or set the <code>scope</code> option, after init.
 857  </dt>
 858  <dd>
 859  <pre><code>//getter
 860  var scope = $('.selector').draggable('option', 'scope');
 861  //setter
 862  $('.selector').draggable('option', 'scope', 'tasks');</code></pre>
 863  </dd>
 864  
 865      </dl>
 866    </div>
 867  </li>
 868  
 869  
 870  <li class="option" id="option-scroll">
 871    <div class="option-header">
 872      <h3 class="option-name"><a href="#option-scroll">scroll</a></h3>
 873      <dl>
 874        <dt class="option-type-label">Type:</dt>
 875          <dd class="option-type">Boolean</dd>
 876        
 877        <dt class="option-default-label">Default:</dt>
 878          <dd class="option-default">true</dd>
 879        
 880      </dl>
 881    </div>
 882    <div class="option-description">
 883      <p>If set to true, container auto-scrolls while dragging.</p>
 884    </div>
 885    <div class="option-examples">
 886      <h4>Code examples</h4>
 887      <dl class="option-examples-list">
 888      
 889  <dt>
 890    Initialize a draggable with the <code>scroll</code> option specified.
 891  </dt>
 892  <dd>
 893  <pre><code>$('.selector').draggable({ scroll: false });</code></pre>
 894  </dd>
 895  
 896      
 897  <dt>
 898    Get or set the <code>scroll</code> option, after init.
 899  </dt>
 900  <dd>
 901  <pre><code>//getter
 902  var scroll = $('.selector').draggable('option', 'scroll');
 903  //setter
 904  $('.selector').draggable('option', 'scroll', false);</code></pre>
 905  </dd>
 906  
 907      </dl>
 908    </div>
 909  </li>
 910  
 911  
 912  <li class="option" id="option-scrollSensitivity">
 913    <div class="option-header">
 914      <h3 class="option-name"><a href="#option-scrollSensitivity">scrollSensitivity</a></h3>
 915      <dl>
 916        <dt class="option-type-label">Type:</dt>
 917          <dd class="option-type">Integer</dd>
 918        
 919        <dt class="option-default-label">Default:</dt>
 920          <dd class="option-default">20</dd>
 921        
 922      </dl>
 923    </div>
 924    <div class="option-description">
 925      <p>Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to pointer, not the draggable.</p>
 926    </div>
 927    <div class="option-examples">
 928      <h4>Code examples</h4>
 929      <dl class="option-examples-list">
 930      
 931  <dt>
 932    Initialize a draggable with the <code>scrollSensitivity</code> option specified.
 933  </dt>
 934  <dd>
 935  <pre><code>$('.selector').draggable({ scrollSensitivity: 40 });</code></pre>
 936  </dd>
 937  
 938      
 939  <dt>
 940    Get or set the <code>scrollSensitivity</code> option, after init.
 941  </dt>
 942  <dd>
 943  <pre><code>//getter
 944  var scrollSensitivity = $('.selector').draggable('option', 'scrollSensitivity');
 945  //setter
 946  $('.selector').draggable('option', 'scrollSensitivity', 40);</code></pre>
 947  </dd>
 948  
 949      </dl>
 950    </div>
 951  </li>
 952  
 953  
 954  <li class="option" id="option-scrollSpeed">
 955    <div class="option-header">
 956      <h3 class="option-name"><a href="#option-scrollSpeed">scrollSpeed</a></h3>
 957      <dl>
 958        <dt class="option-type-label">Type:</dt>
 959          <dd class="option-type">Integer</dd>
 960        
 961        <dt class="option-default-label">Default:</dt>
 962          <dd class="option-default">20</dd>
 963        
 964      </dl>
 965    </div>
 966    <div class="option-description">
 967      <p>The speed at which the window should scroll once the mouse pointer gets within the <code>scrollSensitivity</code> distance.</p>
 968    </div>
 969    <div class="option-examples">
 970      <h4>Code examples</h4>
 971      <dl class="option-examples-list">
 972      
 973  <dt>
 974    Initialize a draggable with the <code>scrollSpeed</code> option specified.
 975  </dt>
 976  <dd>
 977  <pre><code>$('.selector').draggable({ scrollSpeed: 40 });</code></pre>
 978  </dd>
 979  
 980      
 981  <dt>
 982    Get or set the <code>scrollSpeed</code> option, after init.
 983  </dt>
 984  <dd>
 985  <pre><code>//getter
 986  var scrollSpeed = $('.selector').draggable('option', 'scrollSpeed');
 987  //setter
 988  $('.selector').draggable('option', 'scrollSpeed', 40);</code></pre>
 989  </dd>
 990  
 991      </dl>
 992    </div>
 993  </li>
 994  
 995  
 996  <li class="option" id="option-snap">
 997    <div class="option-header">
 998      <h3 class="option-name"><a href="#option-snap">snap</a></h3>
 999      <dl>
1000        <dt class="option-type-label">Type:</dt>
1001          <dd class="option-type">Boolean, Selector</dd>
1002        
1003        <dt class="option-default-label">Default:</dt>
1004          <dd class="option-default">false</dd>
1005        
1006      </dl>
1007    </div>
1008    <div class="option-description">
1009      <p>If set to a selector or to true (equivalent to '.ui-draggable'), the draggable will snap to the edges of the selected elements when near an edge of the element.</p>
1010    </div>
1011    <div class="option-examples">
1012      <h4>Code examples</h4>
1013      <dl class="option-examples-list">
1014      
1015  <dt>
1016    Initialize a draggable with the <code>snap</code> option specified.
1017  </dt>
1018  <dd>
1019  <pre><code>$('.selector').draggable({ snap: true });</code></pre>
1020  </dd>
1021  
1022      
1023  <dt>
1024    Get or set the <code>snap</code> option, after init.
1025  </dt>
1026  <dd>
1027  <pre><code>//getter
1028  var snap = $('.selector').draggable('option', 'snap');
1029  //setter
1030  $('.selector').draggable('option', 'snap', true);</code></pre>
1031  </dd>
1032  
1033      </dl>
1034    </div>
1035  </li>
1036  
1037  
1038  <li class="option" id="option-snapMode">
1039    <div class="option-header">
1040      <h3 class="option-name"><a href="#option-snapMode">snapMode</a></h3>
1041      <dl>
1042        <dt class="option-type-label">Type:</dt>
1043          <dd class="option-type">String</dd>
1044        
1045        <dt class="option-default-label">Default:</dt>
1046          <dd class="option-default">'both'</dd>
1047        
1048      </dl>
1049    </div>
1050    <div class="option-description">
1051      <p>Determines which edges of snap elements the draggable will snap to. Ignored if snap is false. Possible values: 'inner', 'outer', 'both'</p>
1052    </div>
1053    <div class="option-examples">
1054      <h4>Code examples</h4>
1055      <dl class="option-examples-list">
1056      
1057  <dt>
1058    Initialize a draggable with the <code>snapMode</code> option specified.
1059  </dt>
1060  <dd>
1061  <pre><code>$('.selector').draggable({ snapMode: 'outer' });</code></pre>
1062  </dd>
1063  
1064      
1065  <dt>
1066    Get or set the <code>snapMode</code> option, after init.
1067  </dt>
1068  <dd>
1069  <pre><code>//getter
1070  var snapMode = $('.selector').draggable('option', 'snapMode');
1071  //setter
1072  $('.selector').draggable('option', 'snapMode', 'outer');</code></pre>
1073  </dd>
1074  
1075      </dl>
1076    </div>
1077  </li>
1078  
1079  
1080  <li class="option" id="option-snapTolerance">
1081    <div class="option-header">
1082      <h3 class="option-name"><a href="#option-snapTolerance">snapTolerance</a></h3>
1083      <dl>
1084        <dt class="option-type-label">Type:</dt>
1085          <dd class="option-type">Integer</dd>
1086        
1087        <dt class="option-default-label">Default:</dt>
1088          <dd class="option-default">20</dd>
1089        
1090      </dl>
1091    </div>
1092    <div class="option-description">
1093      <p>The distance in pixels from the snap element edges at which snapping should occur. Ignored if snap is false.</p>
1094    </div>
1095    <div class="option-examples">
1096      <h4>Code examples</h4>
1097      <dl class="option-examples-list">
1098      
1099  <dt>
1100    Initialize a draggable with the <code>snapTolerance</code> option specified.
1101  </dt>
1102  <dd>
1103  <pre><code>$('.selector').draggable({ snapTolerance: 40 });</code></pre>
1104  </dd>
1105  
1106      
1107  <dt>
1108    Get or set the <code>snapTolerance</code> option, after init.
1109  </dt>
1110  <dd>
1111  <pre><code>//getter
1112  var snapTolerance = $('.selector').draggable('option', 'snapTolerance');
1113  //setter
1114  $('.selector').draggable('option', 'snapTolerance', 40);</code></pre>
1115  </dd>
1116  
1117      </dl>
1118    </div>
1119  </li>
1120  
1121  
1122  <li class="option" id="option-stack">
1123    <div class="option-header">
1124      <h3 class="option-name"><a href="#option-stack">stack</a></h3>
1125      <dl>
1126        <dt class="option-type-label">Type:</dt>
1127          <dd class="option-type">Object</dd>
1128        
1129        <dt class="option-default-label">Default:</dt>
1130          <dd class="option-default">false</dd>
1131        
1132      </dl>
1133    </div>
1134    <div class="option-description">
1135      <p>Controls the z-Index of the defined group (key 'group' in the hash, accepts jQuery selector) automatically, always brings to front the dragged item. Very useful in things like window managers. Optionally, a 'min' key can be set, so the zIndex cannot go below that value.</p>
1136    </div>
1137    <div class="option-examples">
1138      <h4>Code examples</h4>
1139      <dl class="option-examples-list">
1140      
1141  <dt>
1142    Initialize a draggable with the <code>stack</code> option specified.
1143  </dt>
1144  <dd>
1145  <pre><code>$('.selector').draggable({ stack: { group: 'products', min: 50 } });</code></pre>
1146  </dd>
1147  
1148      
1149  <dt>
1150    Get or set the <code>stack</code> option, after init.
1151  </dt>
1152  <dd>
1153  <pre><code>//getter
1154  var stack = $('.selector').draggable('option', 'stack');
1155  //setter
1156  $('.selector').draggable('option', 'stack', { group: 'products', min: 50 });</code></pre>
1157  </dd>
1158  
1159      </dl>
1160    </div>
1161  </li>
1162  
1163  
1164  <li class="option" id="option-zIndex">
1165    <div class="option-header">
1166      <h3 class="option-name"><a href="#option-zIndex">zIndex</a></h3>
1167      <dl>
1168        <dt class="option-type-label">Type:</dt>
1169          <dd class="option-type">Integer</dd>
1170        
1171        <dt class="option-default-label">Default:</dt>
1172          <dd class="option-default">false</dd>
1173        
1174      </dl>
1175    </div>
1176    <div class="option-description">
1177      <p>z-index for the helper while being dragged.</p>
1178    </div>
1179    <div class="option-examples">
1180      <h4>Code examples</h4>
1181      <dl class="option-examples-list">
1182      
1183  <dt>
1184    Initialize a draggable with the <code>zIndex</code> option specified.
1185  </dt>
1186  <dd>
1187  <pre><code>$('.selector').draggable({ zIndex: 2700 });</code></pre>
1188  </dd>
1189  
1190      
1191  <dt>
1192    Get or set the <code>zIndex</code> option, after init.
1193  </dt>
1194  <dd>
1195  <pre><code>//getter
1196  var zIndex = $('.selector').draggable('option', 'zIndex');
1197  //setter
1198  $('.selector').draggable('option', 'zIndex', 2700);</code></pre>
1199  </dd>
1200  
1201      </dl>
1202    </div>
1203  </li>
1204  
1205      </ul>
1206    </div>
1207    <div id="events">
1208      <h2 class="top-header">Events</h2>
1209      <ul class="events-list">
1210        
1211  <li class="event" id="event-start">
1212    <div class="event-header">
1213      <h3 class="event-name"><a href="#event-start">start</a></h3>
1214      <dl>
1215        <dt class="event-type-label">Type:</dt>
1216          <dd class="event-type">dragstart</dd>
1217      </dl>
1218    </div>
1219    <div class="event-description">
1220      <p>This event is triggered when dragging starts.</p>
1221    </div>
1222    <div class="event-examples">
1223      <h4>Code examples</h4>
1224      <dl class="event-examples-list">
1225      
1226  <dt>
1227    Supply a callback function to handle the <code>start</code> event as an init option.
1228  </dt>
1229  <dd>
1230  <pre><code>$('.selector').draggable({
1231     start: function(event, ui) { ... }
1232  });</code></pre>
1233  </dd>
1234  
1235      
1236  <dt>
1237    Bind to the <code>start</code> event by type: <code>dragstart</code>.
1238  </dt>
1239  <dd>
1240  <pre><code>$('.selector').bind('dragstart', function(event, ui) {
1241    ...
1242  });</code></pre>
1243  </dd>
1244  
1245      </dl>
1246    </div>
1247  </li>
1248  
1249  
1250  <li class="event" id="event-drag">
1251    <div class="event-header">
1252      <h3 class="event-name"><a href="#event-drag">drag</a></h3>
1253      <dl>
1254        <dt class="event-type-label">Type:</dt>
1255          <dd class="event-type">drag</dd>
1256      </dl>
1257    </div>
1258    <div class="event-description">
1259      <p>This event is triggered when the mouse is moved during the dragging.</p>
1260    </div>
1261    <div class="event-examples">
1262      <h4>Code examples</h4>
1263      <dl class="event-examples-list">
1264      
1265  <dt>
1266    Supply a callback function to handle the <code>drag</code> event as an init option.
1267  </dt>
1268  <dd>
1269  <pre><code>$('.selector').draggable({
1270     drag: function(event, ui) { ... }
1271  });</code></pre>
1272  </dd>
1273  
1274      
1275  <dt>
1276    Bind to the <code>drag</code> event by type: <code>drag</code>.
1277  </dt>
1278  <dd>
1279  <pre><code>$('.selector').bind('drag', function(event, ui) {
1280    ...
1281  });</code></pre>
1282  </dd>
1283  
1284      </dl>
1285    </div>
1286  </li>
1287  
1288  
1289  <li class="event" id="event-stop">
1290    <div class="event-header">
1291      <h3 class="event-name"><a href="#event-stop">stop</a></h3>
1292      <dl>
1293        <dt class="event-type-label">Type:</dt>
1294          <dd class="event-type">dragstop</dd>
1295      </dl>
1296    </div>
1297    <div class="event-description">
1298      <p>This event is triggered when dragging stops.</p>
1299    </div>
1300    <div class="event-examples">
1301      <h4>Code examples</h4>
1302      <dl class="event-examples-list">
1303      
1304  <dt>
1305    Supply a callback function to handle the <code>stop</code> event as an init option.
1306  </dt>
1307  <dd>
1308  <pre><code>$('.selector').draggable({
1309     stop: function(event, ui) { ... }
1310  });</code></pre>
1311  </dd>
1312  
1313      
1314  <dt>
1315    Bind to the <code>stop</code> event by type: <code>dragstop</code>.
1316  </dt>
1317  <dd>
1318  <pre><code>$('.selector').bind('dragstop', function(event, ui) {
1319    ...
1320  });</code></pre>
1321  </dd>
1322  
1323      </dl>
1324    </div>
1325  </li>
1326  
1327      </ul>
1328    </div>
1329    <div id="methods">
1330      <h2 class="top-header">Methods</h2>
1331      <ul class="methods-list">
1332        
1333  <li class="method" id="method-destroy">
1334    <div class="method-header">
1335      <h3 class="method-name"><a href="#method-destroy">destroy</a></h3>
1336      <dl>
1337        <dt class="method-signature-label">Signature:</dt>
1338          <dd class="method-signature">.draggable( 'destroy'
1339  
1340  
1341  
1342  
1343  
1344  
1345  
1346  )</dd>
1347      </dl>
1348    </div>
1349    <div class="method-description">
1350      <p>Remove the draggable functionality completely. This will return the element back to its pre-init state.</p>
1351    </div>
1352  </li>
1353  
1354  
1355  <li class="method" id="method-disable">
1356    <div class="method-header">
1357      <h3 class="method-name"><a href="#method-disable">disable</a></h3>
1358      <dl>
1359        <dt class="method-signature-label">Signature:</dt>
1360          <dd class="method-signature">.draggable( 'disable'
1361  
1362  
1363  
1364  
1365  
1366  
1367  
1368  )</dd>
1369      </dl>
1370    </div>
1371    <div class="method-description">
1372      <p>Disable the draggable.</p>
1373    </div>
1374  </li>
1375  
1376  
1377  <li class="method" id="method-enable">
1378    <div class="method-header">
1379      <h3 class="method-name"><a href="#method-enable">enable</a></h3>
1380      <dl>
1381        <dt class="method-signature-label">Signature:</dt>
1382          <dd class="method-signature">.draggable( 'enable'
1383  
1384  
1385  
1386  
1387  
1388  
1389  
1390  )</dd>
1391      </dl>
1392    </div>
1393    <div class="method-description">
1394      <p>Enable the draggable.</p>
1395    </div>
1396  </li>
1397  
1398  
1399  <li class="method" id="method-option">
1400    <div class="method-header">
1401      <h3 class="method-name"><a href="#method-option">option</a></h3>
1402      <dl>
1403        <dt class="method-signature-label">Signature:</dt>
1404          <dd class="method-signature">.draggable( 'option'
1405  
1406  , optionName
1407  
1408  , <span class="optional">[</span>value<span class="optional">] </span>
1409  
1410  
1411  
1412  )</dd>
1413      </dl>
1414    </div>
1415    <div class="method-description">
1416      <p>Get or set any draggable option. If no value is specified, will act as a getter.</p>
1417    </div>
1418  </li>
1419  
1420  
1421      </ul>
1422    </div>
1423    <div id="theming">
1424      <h2 class="top-header">Theming</h2>
1425      <p>The jQuery UI Draggable plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.
1426  </p>
1427    <p>If a deeper level of customization is needed, there are widget-specific classes referenced within the ui.draggable.css stylesheet that can be modified. These classes are highlighed in bold below.
1428  </p>
1429      
1430    <h3>Sample markup with jQuery UI CSS Framework classes</h3>
1431    &lt;div class=&quot;<strong>ui-draggable</strong>&quot;&gt;&lt;/div&gt;
1432    <p class="theme-note">
1433      <strong>
1434        Note: This is a sample of markup generated by the draggable plugin, not markup you should use to create a draggable. The only markup needed for that is &lt;div&gt;&lt;/div&gt;.
1435      </strong>
1436    </p>
1437  
1438    </div>
1439  </div>
1440  
1441  </p><!-- 
1442  Pre-expand include size: 55070 bytes
1443  Post-expand include size: 98892 bytes
1444  Template argument size: 56660 bytes
1445  Maximum: 2097152 bytes
1446  -->
1447  
1448  <!-- Saved in parser cache with key jqdocs_docs:pcache:idhash:3340-1!1!0!!en!2 and timestamp 20090604112209 -->