Droppable Widget

Categories: Interactions

Droppable Widgetversion added: 1.0

Description: Create targets for draggable elements.

QuickNavExamples

Options

Methods

Events

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.

Theming

The droppable widget uses the jQuery UI CSS framework to style its look and feel. If droppable specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

  • ui-droppable: The droppable element. When a draggable that can be dropped on this dropppable is activated, the ui-droppable-active class is added. When dragging a draggable over this droppable, the ui-droppable-hover class is added.

Dependencies

Options

accept 

Type: Selector or Function()
Default: "*"
Controls which draggable elements are accepted by the droppable.
Multiple types supported:
  • Selector: A selector indicating which draggable elements are accepted.
  • 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 should be accepted.
Code examples:

Initialize the droppable with the accept option specified:

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

Get or set the accept option, after initialization:

1
2
3
4
5
 
// Getter
var accept = $( ".selector" ).droppable( "option", "accept" );
 
// Setter
$( ".selector" ).droppable( "option", "accept", ".special" );

activeClass 

Type: String
Default: false

If specified, the class will be added to the droppable while an acceptable draggable is being dragged.

The activeClass option has been deprecated in favor of the classes option, using the ui-droppable-active property.

(version deprecated: 1.12)
Code examples:

Initialize the droppable with the activeClass option specified:

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

Get or set the activeClass option, after initialization:

1
2
3
4
5
 
// Getter
var activeClass = $( ".selector" ).droppable( "option", "activeClass" );
 
// Setter
$( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" );

addClasses 

Type: Boolean
Default: true
If set to false, will prevent the ui-droppable class from being added. This may be desired as a performance optimization when calling .droppable() init on hundreds of elements.
Code examples:

Initialize the droppable with the addClasses option specified:

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

Get or set the addClasses option, after initialization:

1
2
3
4
5
 
// Getter
var addClasses = $( ".selector" ).droppable( "option", "addClasses" );
 
// Setter
$( ".selector" ).droppable( "option", "addClasses", false );

classes 

Type: Object
Default: {}

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the droppable with the classes option specified, changing the theming for the ui-droppable class:

1
2
3
4
5
 
$( ".selector" ).droppable({
  classes: {
    "ui-droppable": "highlight"
  }
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-droppable class:

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).droppable( "option", "classes.ui-droppable" );
 
// Setter
$( ".selector" ).droppable( "option", "classes.ui-droppable", "highlight" );

disabled 

Type: Boolean
Default: false
Disables the droppable if set to true.
Code examples:

Initialize the droppable with the disabled option specified:

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

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).droppable( "option", "disabled" );
 
// Setter
$( ".selector" ).droppable( "option", "disabled", true );

greedy 

Type: Boolean
Default: false
By default, when an element is dropped on nested droppables, each droppable will receive the element. However, by setting this option to true, any parent droppables will not receive the element. The drop event will still bubble normally, but the event.target can be checked to see which droppable received the draggable element.
Code examples:

Initialize the droppable with the greedy option specified:

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

Get or set the greedy option, after initialization:

1
2
3
4
5
 
// Getter
var greedy = $( ".selector" ).droppable( "option", "greedy" );
 
// Setter
$( ".selector" ).droppable( "option", "greedy", true );

hoverClass 

Type: String
Default: false

If specified, the class will be added to the droppable while an acceptable draggable is being hovered over the droppable.

The hoverClass option has been deprecated in favor of the classes option, using the ui-droppable-hover property.

(version deprecated: 1.12)
Code examples:

Initialize the droppable with the hoverClass option specified:

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

Get or set the hoverClass option, after initialization:

1
2
3
4
5
 
// Getter
var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" );
 
// Setter
$( ".selector" ).droppable( "option", "hoverClass", "drop-hover" );

scope 

Type: String
Default: "default"
Used to group sets of draggable and droppable items, in addition to the accept option. A draggable with the same scope value as a droppable will be accepted.
Code examples:

Initialize the droppable with the scope option specified:

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

Get or set the scope option, after initialization:

1
2
3
4
5
 
// Getter
var scope = $( ".selector" ).droppable( "option", "scope" );
 
// Setter
$( ".selector" ).droppable( "option", "scope", "tasks" );

tolerance 

Type: String
Default: "intersect"
Specifies which mode to use for testing whether a draggable is hovering over a droppable. Possible values:
  • "fit": Draggable overlaps the droppable entirely.
  • "intersect": Draggable overlaps the droppable at least 50% in both directions.
  • "pointer": Mouse pointer overlaps the droppable.
  • "touch": Draggable overlaps the droppable any amount.
Code examples:

Initialize the droppable with the tolerance option specified:

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

Get or set the tolerance option, after initialization:

1
2
3
4
5
 
// Getter
var tolerance = $( ".selector" ).droppable( "option", "tolerance" );
 
// Setter
$( ".selector" ).droppable( "option", "tolerance", "fit" );

Methods

destroy()Returns: jQuery (plugin only)

Removes the droppable functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).droppable( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the droppable.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).droppable( "disable" );

enable()Returns: jQuery (plugin only)

Enables the droppable.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).droppable( "enable" );

instance()Returns: Object

Retrieves the droppable's instance object. If the element does not have an associated instance, undefined is returned.

Unlike other widget methods, instance() is safe to call on any element after the droppable plugin has loaded.

  • This method does not accept any arguments.
Code examples:

Invoke the instance method:

1
 
$( ".selector" ).droppable( "instance" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.

Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar" would get the value of the bar property on the foo option.

  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).droppable( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current droppable options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).droppable( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the droppable option associated with the specified optionName.

Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName. For example, "foo.bar" would update only the bar property of the foo option.

  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).droppable( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the droppable.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

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

widget()Returns: jQuery

Returns a jQuery object containing the droppable element.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

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

Events

activate( event, ui )Type: dropactivate

Triggered when an accepted draggable starts dragging. This can be 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
      A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      A jQuery object representing the helper that is being dragged.
    • position
      Type: Object
      Current CSS position of the draggable helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the draggable helper as { top, left } object.
Code examples:

Initialize the droppable with the activate callback specified:

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

Bind an event listener to the dropactivate event:

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

create( event, ui )Type: dropcreate

Triggered when the droppable is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the droppable with the create callback specified:

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

Bind an event listener to the dropcreate event:

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

deactivate( event, ui )Type: dropdeactivate

Triggered when an accepted draggable stops dragging.
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      A jQuery object representing the helper that is being dragged.
    • position
      Type: Object
      Current CSS position of the draggable helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the draggable helper as { top, left } object.
Code examples:

Initialize the droppable with the deactivate callback specified:

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

Bind an event listener to the dropdeactivate event:

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

drop( event, ui )Type: drop

Triggered when an accepted draggable is dropped on the droppable (based on thetolerance option).
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      A jQuery object representing the helper that is being dragged.
    • position
      Type: Object
      Current CSS position of the draggable helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the draggable helper as { top, left } object.
Code examples:

Initialize the droppable with the drop callback specified:

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

Bind an event listener to the drop event:

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

out( event, ui )Type: dropout

Triggered when an accepted draggable is dragged out of the droppable (based on thetolerance option).

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the droppable with the out callback specified:

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

Bind an event listener to the dropout event:

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

over( event, ui )Type: dropover

Triggered when an accepted draggable is dragged over the droppable (based on thetolerance option).
  • event
    Type: Event
  • ui
    Type: Object
    • draggable
      Type: jQuery
      A jQuery object representing the draggable element.
    • helper
      Type: jQuery
      A jQuery object representing the helper that is being dragged.
    • position
      Type: Object
      Current CSS position of the draggable helper as { top, left } object.
    • offset
      Type: Object
      Current offset position of the draggable helper as { top, left } object.
Code examples:

Initialize the droppable with the over callback specified:

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

Bind an event listener to the dropover event:

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

Example:

A pair of draggable and droppable elements.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>droppable demo</title>
  <link rel="stylesheet" href="./code.jquery.com/ui/1.12.0/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.12.4.js"></script>
  <script src="./code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
</head>
<body>
 
<div id="droppable">Drop here</div>
<div id="draggable">Drag me</div>
 
<script>
$( "#draggable" ).draggable();
$( "#droppable" ).droppable({
  drop: function() {
    alert( "dropped" );
  }
});
</script>
 
</body>
</html>

Demo: