jQuery UI API - Droppable Widget
Category
Usage
Description: Create targets for draggable widgets.
Version Added: 1.0
Dependencies:
Note: The jQuery UI Droppable plugin makes selected elements droppable (meaning they accept being dropped on by draggables). You can specify which draggables each will accept.
Quick Navigation
| Options | Methods | Events |
|---|---|---|
| accept activeClass addClasses disabled greedy hoverClass scope tolerance | destroy disable enable option widget | activate create deactivate drop out over |
| Option | Type | Description | Default Value |
|---|---|---|---|
| accept | Selector or Function() | Controls which draggable elements are accepted by the droppable. <br> Supports multiple types: Selector: A selector that specifies which draggable elements are accepted. <br> Function(): A function that will be called for each draggable on the page (passed as the first argument to the function). The function must return true if the draggable is accepted. <br> Code example: Initialize a droppable with the specified accept option: $( ".selector" ).droppable({ accept: ".special" }); <br> After initialization, get or set the accept option: // getter <br> var accept = $( ".selector" ).droppable( "option", "accept" ); <br> // setter <br> $( ".selector" ).droppable( "option", "accept", ".special" ); | "*" |
| activeClass | String | If specified, the class will be added to the droppable while an acceptable draggable is being dragged. <br> Code example: Initialize a droppable with the specified activeClass option: $( ".selector" ).droppable({ activeClass: "ui-state-highlight" }); <br> After initialization, get or set the activeClass option: // getter <br> var activeClass = $( ".selector" ).droppable( "option", "activeClass" ); <br> // setter <br> $( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" ); | false |
| addClasses | Boolean | If set to false, prevents the ui-droppable class from being added. This can improve performance when calling .droppable() on hundreds of elements. <br> Code example: Initialize a droppable with the specified addClasses option: $( ".selector" ).droppable({ addClasses: false }); <br> After initialization, get or set the addClasses option: // getter <br> var addClasses = $( ".selector" ).droppable( "option", "addClasses" ); <br> // setter <br> $( ".selector" ).droppable( "option", "addClasses", false ); | true |
| disabled | Boolean | If set to true, the droppable will be disabled. <br> Code example: Initialize a droppable with the specified disabled option: $( ".selector" ).droppable({ disabled: true }); After initialization, get or set the disabled option: // getter<br>var disabled = $( ".selector" ).droppable( "option", "disabled" );<br> <br>// setter<br>$( ".selector" ).droppable( "option", "disabled", true ); | false |
| greedy | Boolean | By default, when an element is dropped onto a nested droppable, each droppable will receive the element. However, by setting this option to true, any parent droppable will not receive the element. The drop event will still occur as usual, but event.target will be checked to see which droppable received the draggable element. <br> Code example: Initialize a droppable with the specified greedy option: $( ".selector" ).droppable({ greedy: true }); After initialization, get or set the greedy option: // getter<br>var greedy = $( ".selector" ).droppable( "option", "greedy" );<br> <br>// setter<br>$( ".selector" ).droppable( "option", "greedy", true ); | false |
| hoverClass | String | If specified, the class will be added to the droppable when an acceptable draggable is hovered over it. <br> Code example: Initialize a droppable with the specified hoverClass option: $( ".selector" ).droppable({ hoverClass: "drop-hover" }); After initialization, get or set the hoverClass option: // getter<br>var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" );<br> <br>// setter<br>$( ".selector" ).droppable( "option", "hoverClass", "drop-hover" ); | false |
| scope | String | Used to group sets of draggable and droppable items, in addition to the droppable's accept option. A draggable with the same scope value as a droppable will be accepted by the droppable. <br> Code example: Initialize a droppable with the specified scope option: $( ".selector" ).droppable({ scope: "tasks" }); After initialization, get or set the scope option: // getter<br>var scope = $( ".selector" ).droppable( "option", "scope" );<br> <br>// setter<br>$( ".selector" ).droppable( "option", "scope", "tasks" ); | "default" |
| tolerance | String | Specifies the mode used to test whether a draggable is over a droppable. Possible values: <br> "fit": The draggable overlaps completely with the droppable. <br> "intersect": The draggable overlaps with the droppable by at least 50% in both directions. <br> "pointer": The mouse pointer overlaps with the droppable. <br> "touch": The draggable overlaps with the droppable by any amount. Code example: Initialize a droppable with the specified tolerance option: $( ".selector" ).droppable({ tolerance: "fit" }); After initialization, get or set the tolerance option: // getter<br>var tolerance = $( ".selector" ).droppable( "option", "tolerance" );<br> <br>// setter<br>$( ".selector" ).droppable( "option", "tolerance", "fit" ); | "intersect" |
| Method | Returns | Description |
|---|---|---|
| destroy() | jQuery (plugin only) | Completely removes the droppable functionality. This returns the element to its pre-initialization state. <br> This method does not accept any parameters. Code example: Call the destroy method: $( ".selector" ).droppable( "destroy" ); |
| disable() | jQuery (plugin only) | Disables the droppable. <br> This method does not accept any parameters. Code example: Call the disable method: $( ".selector" ).droppable( "disable" ); |
| enable() | jQuery (plugin only) | Enables the droppable. <br> This method does not accept any parameters. Code example: Call the enable method: $( ".selector" ).droppable( "enable" ); |
| option( optionName ) | Object | Gets the value currently associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to get. Code example: Call the method: var isDisabled = $( ".selector" ).droppable( "option", "disabled" ); |
| option() | PlainObject | Gets an object containing key/value pairs representing the current droppable options hash. <br> This method does not accept any parameters. Code example: Call the method: var options = $( ".selector" ).droppable( "option" ); |
| option( optionName, value ) | jQuery (plugin only) | Sets the value of the droppable option associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to set.<br> <br> value<br> Type: Object<br> Description: The value to set for the option. Code example: Call the method: $( ".selector" ).droppable( "option", "disabled", true ); |
| option( options ) | jQuery (plugin only) | Sets one or more options for the droppable. <br> options<br> Type: Object<br> Description: A map of option-value pairs to set. Code example: Call the method: $( ".selector" ).droppable( "option", { disabled: true } ); |
| widget() | jQuery | Returns a jQuery object containing the droppable element. <br> This method does not accept any parameters. Code example: Call the widget method: var widget = $( ".selector" ).droppable( "widget" ); |
| Event | Type | Description |
|---|---|---|
| activate( event, ui ) | dropactivate | Triggered when an acceptable draggable starts dragging. This option can be useful if you want the droppable to "light up" when it is being dropped. <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> draggable<br> Type: jQuery<br> Description: jQuery object representing the draggable element.<br> <br> helper<br> Type: jQuery<br> Description: jQuery object representing the helper being dragged.<br> <br> position<br> Type: Object<br> Description: Current CSS position of the draggable helper, such as { top, left } object.<br> <br> offset<br> Type: Object<br> Description: Current offset position of the draggable helper, such as { top, left } object. Code example: Initialize a droppable with the specified activate callback: $( ".selector" ).droppable({<br> activate: function( event, ui ) {}<br>}); Bind an event listener to the dropactivate event: $( ".selector" ).on( "dropactivate", function( event, ui ) {} ); |
| create( event, ui ) | dropcreate | Triggered when the droppable is created. <br> event<br> Type: Event<br> <br> ui<br> Type: Object Note: The ui object is empty, including it here for consistency with other events. Code example: Initialize a droppable with the specified create callback: $( ".selector" ).droppable({<br> create: function( event, ui ) {}<br>}); 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. <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> draggable<br> Type: jQuery<br> Description: jQuery object representing the draggable element.<br> <br> helper<br> Type: jQuery<br> Description: jQuery object representing the helper being dragged.<br> <br> position<br> Type: Object<br> Description: Current CSS position of the draggable helper, such as { top, left } object.<br> <br> offset<br> Type: Object<br> Description: Current offset position of the draggable helper, such as { top, left } object. Code example: Initialize a droppable with the specified deactivate callback: $( ".selector" ).droppable({<br> deactivate: function( event, ui ) {}<br>}); 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 onto the droppable (based on the tolerance option). <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> draggable<br> Type: jQuery<br> Description: jQuery object representing the draggable element.<br> <br> helper<br> Type: jQuery<br> Description: jQuery object representing the dragged helper.<br> <br> position<br> Type: Object<br> Description: Current CSS position of the draggable helper, such as a { top, left } object.<br> <br> offset<br> Type: Object<br> Description: Current offset position of the draggable helper, such as a { top, left } object. Code example: Initialize the droppable with the specified drop callback: $( ".selector" ).droppable({<br> drop: function( event, ui ) {}<br>}); Bind an event listener to the drop event: $( ".selector" ).on( "drop", function( event, ui ) {} ); |
| out(event, ui) | dropout | Triggered when the draggable is dragged out of the droppable (based on the tolerance option). <br> event<br> Type: Event<br> <br> ui<br> Type: Object Note: The ui object is empty, including it here for consistency with other events. Code example: Initialize the droppable with the specified out callback: $( ".selector" ).droppable({<br> out: function( event, ui ) {}<br>}); 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 on the tolerance option). <br> event<br> Type: Event<br> <br> ui<br> Type: Object<br> <br> draggable<br> Type: jQuery<br> Description: jQuery object representing the draggable element.<br> <br> helper<br> Type: jQuery<br> Description: jQuery object representing the dragged helper.<br> <br> position<br> Type: Object<br> Description: Current CSS position of the draggable helper, such as a { top, left } object.<br> <br> offset<br> Type: Object<br> Description: Current offset position of the draggable helper, such as a { top, left } object. Code example: Initialize the droppable with the specified over callback: $( ".selector" ).droppable({<br> over: function( event, ui ) {}<br>}); Bind an event listener to the dropover event: $( ".selector" ).on( "dropover", function( event, ui ) {} ); |
Example
A pair of draggable and droppable elements.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Droppable Widget Demo</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;
```html
<style>
#droppable, #draggable {
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">Please drop here!</div>
<div id="draggable">Please drag me!</div>
<script>
$( "#draggable" ).draggable();
$( "#droppable" ).droppable({
drop: function() {
alert( "dropped" );
}
});
</script>
</body>
</html>