jQuery UI API - Droppable Widget

Category

Interactions

Usage

Description:Create targets for draggable widgets.

Added in version:1.0

Dependencies:

Notes:The jQuery UI Droppable plugin makes selected elements droppable (meaning they accept being dropped after being dragged). You can specify which draggable elements will be accepted individually.

Quick Navigation

Options Methods Events

Options Type Description Default
accept Selector or Function() Controls which draggable elements can be accepted by the droppable.

Supports multiple types:

  • Selector: A selector specifying which draggable elements can be accepted by the droppable.
  • Function(): A function that will be called for each draggable on the page (passed to the function as the first argument). If the draggable is accepted, the function must returntrue。

Code examples:

Initialize the droppable with the specifiedacceptoption:

$( ".selector" ).droppable({ accept: ".special" });
    

After initialization, get or setacceptthe option:

// getter
var accept = $( ".selector" ).droppable( "option", "accept" );
 
// setter
$( ".selector" ).droppable( "option", "accept", ".special" );
    
 "*"
activeClass String If specified, the class will be added to the droppable when an acceptable draggable starts being dragged.

Code examples:

Initialize the droppable with the specifiedactiveClassoption:

$( ".selector" ).droppable({ activeClass: "ui-state-highlight" });
    

After initialization, get or setactiveClassthe option:

// getter
var activeClass = $( ".selector" ).droppable( "option", "activeClass" );
 
// setter
$( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" );
    
 false
addClasses Boolean If set tofalse, will preventui-droppablethe class from being added. When calling on hundreds of elements.droppable()it helps performance optimization.

Code examples:

Initialize the droppable with the specifiedaddClassesoption:

$( ".selector" ).droppable({ addClasses: false });
    

After initialization, get or setaddClassesthe option:

// getter
var addClasses = $( ".selector" ).droppable( "option", "addClasses" );
 
// setter
$( ".selector" ).droppable( "option", "addClasses", false );
    
 true
disabled Boolean If set totrue, the droppable is disabled.

Code examples:

Initialize the droppable with the specifieddisabledoption:

$( ".selector" ).droppable({ disabled: true });
    

After initialization, get or setdisabledthe option:

// getter
var disabled = $( ".selector" ).droppable( "option", "disabled" );
 
// setter
$( ".selector" ).droppable( "option", "disabled", true );
    
 false
greedy Boolean By default, when an element is dropped on nested droppables, each droppable will receive the element. However, by setting this option totrue, any parent element's droppable will not receive the element.dropEvents will still fire as usual, but it will checkevent.targetto see which droppable receives the draggable element.

Code examples:

Initialize the droppable with the specifiedgreedyoption:

$( ".selector" ).droppable({ greedy: true });
    

After initialization, get or setgreedythe option:

// getter
var greedy = $( ".selector" ).droppable( "option", "greedy" );
 
// setter
$( ".selector" ).droppable( "option", "greedy", true );
    
 false
hoverClass String If specified, the class will be added to the droppable when an acceptable draggable is over the droppable.

Code examples:

Initialize the droppable with the specifiedhoverClassoption:

$( ".selector" ).droppable({ hoverClass: "drop-hover" });
    

After initialization, get or sethoverClassthe option:

// getter
var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" );
 
// setter
$( ".selector" ).droppable( "option", "hoverClass", "drop-hover" );
    
 false
scope String Used to group paired draggable and droppable items, in addition to the droppable'sacceptoption. A draggable with the samescopevalue as the droppable will be accepted by that droppable.

Code examples:

Initialize the droppable with the specifiedscopeoption:

$( ".selector" ).droppable({ scope: "tasks" });
    

After initialization, get or setscopethe option:

// getter
var scope = $( ".selector" ).droppable( "option", "scope" );
 
// setter
$( ".selector" ).droppable( "option", "scope", "tasks" );
    
 "default"
tolerance String Specifies the mode used to test whether a draggable is over a droppable. Possible values:
  • "fit": The draggable completely overlaps the droppable.
  • "intersect": The draggable overlaps the droppable by at least 50% in both directions.
  • "pointer": The mouse pointer overlaps the droppable.
  • "touch": The draggable overlaps the droppable by any amount.

Code examples:

Initialize the droppable with the specifiedtoleranceoption:

$( ".selector" ).droppable({ tolerance: "fit" });
    

After initialization, get or settolerancethe option:

// getter
var tolerance = $( ".selector" ).droppable( "option", "tolerance" );
 
// setter
$( ".selector" ).droppable( "option", "tolerance", "fit" );
    
 "intersect"

Methods Returns Description
destroy() jQuery (plugin only) Completely remove the droppable functionality. This will return the element to its pre-init state.
  • This method does not accept any arguments.

Code examples:

Invoke the destroy method:

$( ".selector" ).droppable( "destroy" );
    
disable() jQuery (plugin only) Disable the droppable.
  • This method does not accept any arguments.

Code examples:

Invoke the disable method:

$( ".selector" ).droppable( "disable" );
    
enable() jQuery (plugin only) Enable the droppable.
  • This method does not accept any arguments.

Code examples:

Invoke the enable method:

$( ".selector" ).droppable( "enable" );
    
option( optionName ) Object Get the value currently associated with the specifiedoptionNameoption.
  • optionName
    Type: String
    Description: The name of the option to get.

Code examples:

Invoke this method:

var isDisabled = $( ".selector" ).droppable( "option", "disabled" );
    
option() PlainObject Get an object containing key/value pairs representing the current droppable option hash.
  • This method does not accept any arguments.

Code examples:

Invoke this method:

var options = $( ".selector" ).droppable( "option" );
    
option( optionName, value ) jQuery (plugin only) Set the value of the droppable option associated with the specifiedoptionNameoption.
  • optionName
    Type: String
    Description: The name of the option to set.
  • value
    Type: Object
    Description: The value to set for the option.

Code examples:

Invoke this method:

$( ".selector" ).droppable( "option", "disabled", true );
    
option( options ) jQuery (plugin only) Set one or more options for the droppable.
  • options
    Type: Object
    Description: The option-value pairs to set.

Code examples:

Invoke this method:

$( ".selector" ).droppable( "option", { disabled: true } );
    
widget() jQuery Return anjQueryobject containing the droppable element.
  • This method does not accept any arguments.

Code examples:

Invoke the widget method:

var widget = $( ".selector" ).droppable( "widget" );
    

Events Type Description
activate( event, ui ) dropactivate Triggered when an acceptable draggable starts dragging. This option is useful if you want to make the droppable "light up" when it can be dropped on.
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      Description: A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      Description: A jQuery object representing the dragged helper.
    • position
      Type: Object
      Description: The current CSS position of the draggable helper, such as{ top, left }object.
    • offset
      Type: Object
      Description: The current offset position of the draggable helper, such as{ top, left }object.

Code examples:

Initialize the droppable with the specified activate callback:

$( ".selector" ).droppable({
  activate: function( event, ui ) {}
});
    

Bind an event listener to the dropactivate event:

$( ".selector" ).on( "dropactivate", function( event, ui ) {} );
    
create( event, ui ) dropcreate Triggered when the droppable is created.
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty; it is included here for consistency with other events.

Code examples:

Initialize the droppable with the specified create callback:

$( ".selector" ).droppable({
  create: function( event, ui ) {}
});
    

Bind an event listener to the dropcreate event:

$( ".selector" ).on( "dropcreate", function( event, ui ) {} );
    
deactivate( event, ui ) dropdeactivate Triggered when an acceptable draggable stops dragging.
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      Description: A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      Description: A jQuery object representing the draggable helper.
    • position
      Type: Object
      Description: The current CSS position of the draggable helper, such as{ top, left }object.
    • offset
      Type: Object
      Description: The current offset position of the draggable helper, such as{ top, left }object.

Code examples:

Initialize the droppable with the specified deactivate callback:

$( ".selector" ).droppable({
  deactivate: function( event, ui ) {}
});
    

Bind an event listener to the dropdeactivate event:

$( ".selector" ).on( "dropdeactivate", function( event, ui ) {} );
    
drop( event, ui ) drop Triggered when an acceptable draggable is dropped on the droppable (based ontolerancethe option).
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      Description: A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      Description: A jQuery object representing the draggable helper.
    • position
      Type: Object
      Description: The current CSS position of the draggable helper, such as{ top, left }object.
    • offset
      Type: Object
      Description: The current offset position of the draggable helper, such as{ top, left }object.

Code examples:

Initialize the droppable with the specified drop callback:

$( ".selector" ).droppable({
  drop: function( event, ui ) {}
});
    

Bind an event listener to the drop event:

$( ".selector" ).on( "drop", function( event, ui ) {} );
    
out( event, ui ) dropout Triggered when a draggable is dragged out of the droppable (based ontolerancethe option).
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty; it is included here for consistency with other events.

Code examples:

Initialize the droppable with the specified out callback:

$( ".selector" ).droppable({
  out: function( event, ui ) {}
});
    

Bind an event listener to the dropout event:

$( ".selector" ).on( "dropout", function( event, ui ) {} );
    
over( event, ui ) dropover Triggered when an acceptable draggable is dragged over the droppable (based ontolerancethe option).
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      Description: A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      Description: A jQuery object representing the draggable helper.
    • position
      Type: Object
      Description: The current CSS position of the draggable helper, such as{ top, left }object.
    • offset
      Type: Object
      Description: The current offset position of the draggable helper, such as{ top, left }object.

Code examples:

Initialize the droppable with the specified over callback:

$( ".selector" ).droppable({
  over: function( event, ui ) {}
});
    

Bind an event listener to the dropover event:

$( ".selector" ).on( "dropover", function( event, ui ) {} );
    

Examples

A pair of draggable and droppable elements.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可放置小部件（Droppable Widget）演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  #droppable {
    position: absolute;
    left: 250px;
    top: 0;
    width: 125px;
    height: 125px;
    background: #999;
    color: #fff;
    padding: 10px;
  }
  </style>
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
 
<div id="droppable">请放置到这里！</div>
<div id="draggable">请拖拽我！</div>
 
<script>
$( "#draggable" ).draggable();
$( "#droppable" ).droppable({
  drop: function() {
    alert( "dropped" );
  }
});
</script>
 
</body>
</html>

Other Extensions