Wp Admin Drag And Drop

WordPress Admin Drag-and-Drop

WP ships a complete jQuery UI drag-and-drop toolkit and the WAI-ARIA helper core itself uses to announce moves. You do not need SortableJS, dnd-kit, or Dragula for an admin UI. The blocker isn't the API — it's that nobody documents which primitive matches which UX a plugin developer actually wants to build. This skill is that mapping.

When to use this skill

Trigger when ANY of the following is true:

• A plugin admin page needs drag-to-reorder for ANY list of items — repeater rows, custom builder cards, rule-priority lists, sortable form fields, custom taxonomy term order, FAQ entries, pricing tiers, notification levels.
• The user wants a palette of available items that get dragged into a drop zone — block-library-like UIs, condition builders, action chains.
• The user wants a kanban-style board, or any "move card between columns" UX.
• The user asks for "menu-style" or "parent/child" drag — nested trees with indentation.
• The user is reaching for an external D&D library for admin UI when WP's bundled primitives would do.
• Code references jquery-ui-sortable, jquery-ui-draggable, jquery-ui-droppable, jquery-touch-punch, connectWith, connectToSortable.

Proof this is reusable: where core itself runs these primitives

Same three jQuery UI plugins, four wildly different UXes. If your plugin scenario looks like ANY of these, the same toolkit works for you.

This isn't theoretical — these are stable, production WP features, all built on the same three handles: jquery-ui-sortable, jquery-ui-draggable, jquery-ui-droppable.

What you enqueue

The handles are pre-registered in wp-includes/script-loader.php. Declare them as deps:

add_action( 'admin_enqueue_scripts', static function ( string $hook_suffix ): void {
    if ( 'settings_page_myplugin' !== $hook_suffix ) {
        return;
    }
    wp_enqueue_script(
        'myplugin-builder',
        plugins_url( 'assets/builder.js', MYPLUGIN_FILE ),
        array(
            'jquery-ui-sortable',     // pick whichever you actually need
            'jquery-ui-draggable',    // — leave the rest out
            'jquery-ui-droppable',
            'jquery-touch-punch',     // optional: touch device support
            'wp-a11y',                // for wp.a11y.speak()
            'wp-i18n',                // for wp.i18n translations in announcements
            'wp-api-fetch',           // for persisting order via REST
        ),
        MYPLUGIN_VERSION,
        array( 'in_footer' => true )
    );
} );

Decision tree

Pattern 1 — flat sortable list

The most common plugin scenario. Repeater rows in a settings page, FAQ items, rule lists, pricing tiers, anything where order matters but there's no hierarchy.

jQuery( function ( $ ) {
    $( '#myplugin-rules' ).sortable( {
        items: '> .rule-row',
        handle: '.rule-handle',
        placeholder: 'rule-placeholder',
        cursor: 'move',
        tolerance: 'pointer',
        forcePlaceholderSize: true,
        update: function () {
            const $list = $( this );
            const order = $( this ).sortable( 'toArray', { attribute: 'data-rule-id' } );
            $list.sortable( 'disable' );
            wp.apiFetch( {
                path: '/myplugin/v1/rules/order',
                method: 'POST',
                data: { order },
            } ).then( () => {
                wp.a11y.speak( wp.i18n.__( 'Order saved.', 'myplugin' ) );
            } ).catch( () => {
                wp.a11y.speak( wp.i18n.__( 'Order was not saved. Reloading.', 'myplugin' ) );
                window.location.reload(); // Restore canonical server order.
            } ).finally( () => $list.sortable( 'enable' ) );
        },
    } );
} );

Why toArray({ attribute: 'data-rule-id' }) instead of DOM id: in repeater rows cloned from a template, DOM ids tend to collide. Use data-* attributes — that's what production builders do.

For metabox-style flat lists (with collapse + Screen Options), see wp-admin-postbox-sortable — that's the special-case skill for the postbox-specific chrome.

Pattern 2 — connected lists (kanban / move between zones)

When you have multiple lists and items can move between them. Plugin use cases: kanban board for membership states, two-column "available / enabled" toggles, status-bucket UIs, multi-tier rule sets where rules can be promoted/demoted.

const $columns = $( '.builder-column' );

$columns.sortable( {
    connectWith: '.builder-column',
    items: '> .builder-card',
    handle: '.card-handle',
    placeholder: 'card-placeholder',
    forcePlaceholderSize: true,
    update: function ( event, ui ) {
        if ( ui.sender ) {
            return; // The sender list also fires update; only persist once.
        }
        const payload = {};
        $columns.each( function () {
            payload[ this.id ] = $( this ).sortable( 'toArray', { attribute: 'data-card-id' } );
        } );
        wp.apiFetch( {
            path: '/myplugin/v1/cards/order',
            method: 'POST',
            data: payload,
        } ).then( () => {
            wp.a11y.speak( wp.i18n.__( 'Board updated.', 'myplugin' ) );
        } ).catch( () => {
            wp.a11y.speak( wp.i18n.__( 'Board was not saved. Reloading.', 'myplugin' ) );
            window.location.reload();
        } );
    },
} );

The critical gotcha: a cross-list move fires update on both the sender and the receiver. Dedupe on ui.sender (truthy only on the receiving list), or you'll double-save.

Pattern 3 — palette + drop zones

When you have a fixed library of items on one side, drop zones on the other. The palette item stays put (it clones); a new item lands in the drop zone. Plugin use cases: block library, action library for a logic builder, available-tags panel, condition builder.

// Draggable owns connectToSortable; the palette remains because helper is a clone.
$paletteItems.draggable( { connectToSortable: '.dropzone', helper: 'clone' } );
$dropzones.sortable( { receive: convertCloneToPersistedItem } );

connectToSortable belongs to Draggable, and helper: 'clone' keeps the source item. receive must persist the new item, replace the temporary clone only on success, and remove it on failure. The complete async example is in reference.md.

Pattern 4 — hierarchical / nested (parent + child indentation)

When you need tree behavior with depth indentation that updates while dragging. Plugin use cases: hierarchical taxonomy term reorder with nesting, page-tree style site map, file/folder tree, parent/child rule grouping.

The algorithm:

• Depth is rendered as margin-left: depth * STEP_PX (or as a .item-depth-N class). NOT as nested <ul> markup.
• During drag: read the helper's x-offset and clamp not only to [0, MAX_DEPTH], but also to the structural limit: at most one level deeper than the previous visible row. Account for the dragged subtree so no child exceeds MAX_DEPTH.
• Children = following siblings whose depth is greater than the dragged item. At drag-start, detach them into a transport element so the placeholder sizes correctly; at drag-stop, re-insert them after the parent and shift their depth classes by the same delta.

When persisting: walk the DOM in order, each item's parent is "the previous item with depth = current depth − 1". Server side this collapses to a flat list with parent_id per row.

See reference.md for a compact implementation. For a battle-tested implementation, read wp-admin/js/nav-menu.js:885; it includes RTL handling, accessibility hooks, and menu-specific bits most plugins don't need.

Pattern 5 — droppable trash / status bucket

When the target isn't a sortable list — a delete zone, a "send to archive" bucket, a star/favorite area, a "test now" tray.

$( '#trash-zone' ).droppable( {
    accept: '.tree-item, .rule, .placed-item',
    activeClass: 'trash-zone-active',  // while ANY draggable is being dragged
    hoverClass:  'trash-zone-hover',   // while a valid item is over us
    tolerance: 'pointer',
    drop: function ( event, ui ) {
        const id = ui.draggable.data( 'item-id' );
        ui.draggable.addClass( 'is-pending' ).attr( 'aria-disabled', 'true' );
        wp.apiFetch( {
            path: `/myplugin/v1/items/${ id }`,
            method: 'DELETE',
        } ).then( () => {
            ui.draggable.fadeOut( 150, () => ui.draggable.remove() );
            wp.a11y.speak( wp.i18n.__( 'Item deleted.', 'myplugin' ) );
        } ).catch( () => {
            ui.draggable.removeClass( 'is-pending' ).removeAttr( 'aria-disabled' );
            wp.a11y.speak( wp.i18n.__( 'Item could not be deleted.', 'myplugin' ) );
        } );
    },
} );

Useful even when you don't need a "trash" — same pattern works for "click-drag a campaign onto a date in a mini-calendar", "drag a user onto a role bucket", "drop a product onto a category preview". Any target that isn't itself a sortable list.

Persisting order — REST, not admin-ajax

Don't reach for admin-ajax.php for new endpoints. Use REST with a real permission_callback, validation plus sanitization (order as a positive integer array), and wp-api-fetch on the client. Server-side, verify that the submitted IDs are the complete allowed set for that user/container: an args schema cannot detect omitted, foreign, or duplicate business objects. wp-api-fetch attaches X-WP-Nonce for the standard cookie-authenticated WordPress setup when its nonce middleware is configured by core.

Accessibility — match the postbox keyboard pattern

Pointer-only drag is a WCAG fail. The pattern WP itself ships: a pair of "move up / move down" buttons per item alongside the drag handle, with wp.a11y.speak() announcements. Match it.

Use real buttons, not only a draggable handle. The click handler moves the row in the DOM, calls the same persistence routine as drag-drop, and announces with wp.a11y.speak(). See reference.md for the snippet and postbox.handleOrder() in wp-admin/js/postbox.js:98 for core's pattern.

Touch support

jQuery UI's drag handlers remain mouse-oriented. For touch devices, add jquery-touch-punch as a dep — it patches jQuery UI mouse interactions to also accept touch events. It's registered in core, so declaring it as a dep is enough. Test real touch and keyboard behavior: the old patch is compatibility support, not a modern pointer-events accessibility layer.

WordPress 7.1 updates the bundled jQuery UI components from 1.13.3 to 1.14.2 and sets jQuery.uiBackCompat = true before jquery-ui-core. The documented widget APIs used in this skill remain available, but plugin code that reaches into underscored widget methods, copied internals, DOM-generated class details, or deprecated $.ui.plugin behavior must be regression-tested. Core's back-compat flag is not a promise that private internals are stable.

Critical rules

• Prefer core's jQuery UI handles for conventional PHP-rendered admin UI. Complex pointer/touch interactions or React-rendered surfaces may justify a maintained external library; account for its bundle, accessibility, and lifecycle costs explicitly.
• Always provide a keyboard reorder path. Pointer-only D&D fails WCAG. Postbox-style move-up / move-down buttons + wp.a11y.speak is the WP pattern; match it.
• update fires on both the sender and the receiver during a cross-list move. Dedupe on ui.sender or you'll double-save.
• receive runs BEFORE update on the receiving list. Convert palette stubs into real items in receive, persist final order in update.
• Don't initialize a sortable on a collection you'll re-render server-side. After an AJAX HTML swap, call $container.sortable( 'destroy' ) before re-initializing — otherwise items get duplicate event bindings.
• Hierarchical depth is geometry, not DOM nesting. The nav-menu / Pattern 4 approach uses a flat sibling list with depth classes, NOT nested <ul> containers. This is what lets items move across parents — there are no nested containers to "leave".
• Don't track item position in client-side state. Read from the DOM (sortable('toArray')) at persist time. The DOM IS the model.
• Persist on update, not on change or sort. change / sort fire continuously during drag; update fires once on drop. AJAX storms are the result of confusing them.

Common AI mistakes

See reference.md for before/after snippets: flat sortable used for trees, connectToSortable placed on the wrong primitive, persisting on change, missing wp.a11y.speak(), and adding new admin-ajax handlers instead of REST routes.

Cross-references

• See wp-admin-postbox-sortable for the metabox special case (collapse + Screen Options + the two nonce fields plugins forget).
• See wp-plugin-assets-loading for the canonical way to declare these jQuery UI handles as deps without globally bloating admin.
• See wp-rest-api for the order-persistence endpoint shape (permission_callback, args schema, capability checks).

What this skill does NOT cover

• React / Gutenberg drag-and-drop. Inside the block editor or any React island, @dnd-kit/core is the idiomatic choice. jQuery UI doesn't fit there.
• Extending the existing nav-menus admin (the menu builder you see in Appearance → Menus). That's a separate topic — wp_setup_nav_menu_item filter, walker_nav_menu_edit.
• File drag-and-drop into the media library. Media uses wp-plupload (HTML5 file drop), which is a different primitive.

Where to look in core for proof / reference

You don't need to read these to use the patterns above — they're listed for when you want a battle-tested implementation to copy from.

• wp-admin/js/postbox.js — flat sortable (init at line 369), keyboard reorder buttons (line 98).
• wp-admin/js/widgets.js:195 and :271 — palette + drop-zone pattern.
• wp-admin/js/nav-menu.js:885 — hierarchical sortable with depth math.
• wp-includes/script-loader.php — the jquery-ui-draggable, jquery-ui-droppable, jquery-ui-sortable registrations and bundled version.
• reference.md — hierarchical tree snippet, keyboard reorder snippet, and common mistakes.

References

• Official documentation: https://api.jqueryui.com/sortable/
• Official documentation: https://api.jqueryui.com/draggable/
• Official documentation: https://api.jqueryui.com/droppable/