jQuery UI droppable documentation

## Droppable Widgetversion added: 1.0

Description: Create targets for draggable elements.

## QuickNavExamples

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.

## Options

### acceptType: 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:

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

Get or set the accept option, after initialization:

`// getter` `var` `accept = $(` `".selector"` `).droppable(` `"option"``,` `"accept"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"accept"``,` `".special"` `);`

### activeClassType: String

Default: `false`
If specified, the class will be added to the droppable while an acceptable draggable is being dragged.
Code examples:

Initialize the droppable with the activeClass option specified:

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

Get or set the activeClass option, after initialization:

`// getter` `var` `activeClass = $(` `".selector"` `).droppable(` `"option"``,` `"activeClass"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"activeClass"``,` `"ui-state-highlight"` `);`

### addClassesType: 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:

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

Get or set the addClasses option, after initialization:

`// getter` `var` `addClasses = $(` `".selector"` `).droppable(` `"option"``,` `"addClasses"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"addClasses"``,` `false` `);`

### disabledType: Boolean

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

Initialize the droppable with the disabled option specified:

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

Get or set the disabled option, after initialization:

`// getter` `var` `disabled = $(` `".selector"` `).droppable(` `"option"``,` `"disabled"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"disabled"``,` `true` `);`

### greedyType: 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.
Code examples:

Initialize the droppable with the greedy option specified:

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

Get or set the greedy option, after initialization:

`// getter` `var` `greedy = $(` `".selector"` `).droppable(` `"option"``,` `"greedy"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"greedy"``,` `true` `);`

### hoverClassType: String

Default: `false`
If specified, the class will be added to the droppable while an acceptable draggable is being hovered over the droppable.
Code examples:

Initialize the droppable with the hoverClass option specified:

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

Get or set the hoverClass option, after initialization:

`// getter` `var` `hoverClass = $(` `".selector"` `).droppable(` `"option"``,` `"hoverClass"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"hoverClass"``,` `"drop-hover"` `);`

### scopeType: 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:

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

Get or set the scope option, after initialization:

`// getter` `var` `scope = $(` `".selector"` `).droppable(` `"option"``,` `"scope"` `);` `// setter` `$(` `".selector"` `).droppable(` `"option"``,` `"scope"``,` `"tasks"` `);`

### toleranceType: 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:

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

Get or set the tolerance option, after initialization:

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

## Methods

### destroy()

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:

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

### disable()

Disables the droppable.

- This method does not accept any arguments.

Code examples:

Invoke the disable method:

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

### enable()

Enables the droppable.

- This method does not accept any arguments.

Code examples:

Invoke the enable method:

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

### option( optionName )Returns: Object

Gets the value currently associated with the specified `optionName`.

- optionName
  Type: String
  The name of the option to get.

Code examples:

Invoke the method:

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

### option()Returns: PlainObject

Gets an object containing key/value pairs representing the current droppable options hash.

- This method does not accept any arguments.

Code examples:

Invoke the method:

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

### option( optionName, value )

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

- 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:

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

### option( options )

Sets one or more options for the droppable.

- options
  Type: Object
  A map of option-value pairs to set.

Code examples:

Invoke the method:

`$(` `".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:

`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:

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

Bind an event listener to the dropactivate event:

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

### create( event, ui )Type: `dropcreate`

Triggered when the droppable is created.

- event
  Type: Event
- ui
  Type: Object

Code examples:

Initialize the droppable with the create callback specified:

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

Bind an event listener to the dropcreate event:

`$(` `".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:

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

Bind an event listener to the dropdeactivate event:

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

### drop( event, ui )Type: `drop`

Triggered when an accepted draggable is dropped on the droppable (based on the`tolerance` 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:

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

Bind an event listener to the drop event:

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

### out( event, ui )Type: `dropout`

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

- event
  Type: Event
- ui
  Type: Object

Code examples:

Initialize the droppable with the out callback specified:

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

Bind an event listener to the dropout event:

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

### over( event, ui )Type: `dropover`

Triggered when an accepted draggable is dragged over the droppable (based on the`tolerance` 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:

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

Bind an event listener to the dropover event:

`$(` `".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``=``"http://code.jquery.com/ui/1.9.2/themes/base/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``=``"http://code.jquery.com/jquery-1.8.3.js"``></``script``>` `` `<``script` `src``=``"http://code.jquery.com/ui/1.9.2/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: