wp_enqueue_media() and wp.media(). Covers the screen-gated\nenqueue, media-editor dependency, wp.media( { frame, title, button, library, multiple } ), library filters for type / MIME / uploadedTo /\nauthor, multiple values true and 'add', select and open events,\nframe.state().get( 'selection' ).first().toJSON(), attachment sizes,\nframe caching, pre-selecting existing attachments, and saving attachment\nIDs instead of URLs. Use for image, file, gallery, logo, avatar, cover,\nor per-row icon pickers in settings pages, metaboxes, and repeaters.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"wordpress\"\nwp-skills-plugin-version-tested: \"6.0 - 7.1\"\nwp-skills-wp-version-tested: \"7.1\"\nwp-skills-php-min: \"7.4\"\nwp-skills-last-updated: \"2026-08-20\"wp.media)The Media Library modal is the same Backbone-driven UI WP uses for \"Add Media\" on the post editor. Plugins reuse it for logo pickers, avatar fields, gallery builders, per-row icon selectors — anything that wants \"open the WP media library, let the user pick or upload, hand me back an attachment\". The blocker is almost always the bootstrap, not the API.
\nTrigger when ANY of the following is true:
\nwp.media, wp.media.frame, wp_enqueue_media, wp_prepare_attachment_for_js, frame.state().get( 'selection' ), library: { type: ... }, multiple: 'add', or the MediaFrame.Select / MediaFrame.Post types.Like every other WP admin JS API, the media frame needs (1) a PHP enqueue, (2) the right asset deps in your JS, (3) the JS init at DOM-ready. Miss any one and you get wp.media is undefined or a silent no-op.
wp_enqueue_media() on YOUR screen onlywp_enqueue_media() is idempotent (it guards on did_action( 'wp_enqueue_media' )), but it enqueues ~12 scripts and a stylesheet. Don't call it globally.
add_action( 'admin_enqueue_scripts', static function ( string $hook_suffix ): void {\n if ( 'settings_page_myplugin' !== $hook_suffix ) {\n return;\n }\n\n wp_enqueue_media();\n\n wp_enqueue_script(\n 'myplugin-media-picker',\n plugins_url( 'assets/media-picker.js', MYPLUGIN_FILE ),\n array( 'jquery', 'media-editor', 'wp-i18n' ),\n MYPLUGIN_VERSION,\n array( 'in_footer' => true )\n );\n} );\nDeclare media-editor as a dependency because it supplies the editor-facing\nmedia API and depends on the underlying media-views stack. It is not a\nlightweight alternative to that stack; wp_enqueue_media() loads the media\nmodels, views, settings, templates, and styles required by the frame.
The picker needs a trigger button, a hidden input to store the attachment ID, and a preview spot. Keep the input as the source of truth — server-side you save the ID, not the URL.
\n<div class=\"myplugin-image-field\" data-target=\"logo\">\n <input\n type=\"hidden\"\n id=\"myplugin_logo_id\"\n name=\"myplugin_options[logo_id]\"\n value=\"<?php echo esc_attr( $options['logo_id'] ?? '' ); ?>\"\n />\n <div class=\"myplugin-image-preview\">\n <?php\n if ( ! empty( $options['logo_id'] ) ) {\n echo wp_get_attachment_image( (int) $options['logo_id'], 'thumbnail' );\n }\n ?>\n </div>\n <button type=\"button\" class=\"button myplugin-image-pick\">\n <?php esc_html_e( 'Choose image', 'myplugin' ); ?>\n </button>\n <button type=\"button\" class=\"button myplugin-image-remove\">\n <?php esc_html_e( 'Remove', 'myplugin' ); ?>\n </button>\n</div>\njQuery( function ( $ ) {\n let frame;\n\n $( '.myplugin-image-pick' ).on( 'click', function ( e ) {\n e.preventDefault();\n\n // Cache the frame — opening a new one every click is wasteful and\n // loses the \"previously selected\" state.\n if ( frame ) {\n frame.open();\n return;\n }\n\n frame = wp.media( {\n title: wp.i18n.__( 'Choose image', 'myplugin' ),\n button: { text: wp.i18n.__( 'Use this image', 'myplugin' ) },\n library: { type: 'image' },\n multiple: false,\n } );\n\n frame.on( 'select', function () {\n const attachment = frame.state().get( 'selection' ).first().toJSON();\n\n // Store the ID — the source of truth.\n $( '#myplugin_logo_id' ).val( attachment.id );\n\n // Render a thumbnail preview. CRITICAL: pick the right size — see below.\n const thumb = attachment.sizes && attachment.sizes.thumbnail\n ? attachment.sizes.thumbnail.url\n : attachment.url;\n $( '.myplugin-image-preview' )\n .empty()\n .append( $( '<img>', { src: thumb, alt: '' } ) );\n } );\n\n frame.open();\n } );\n\n $( '.myplugin-image-remove' ).on( 'click', function ( e ) {\n e.preventDefault();\n $( '#myplugin_logo_id' ).val( '' );\n $( '.myplugin-image-preview' ).empty();\n } );\n} );\nwp.media( { frame: 'select', ... } ) is the default and covers almost every plugin picker. Use 'post' only when re-creating the classic-editor Add Media flow, and avoid internal frames such as 'manage' / 'edit-attachments' in normal plugin settings screens.
The library attribute is a wp.media.query filter. Common shapes: library: { type: 'image' }, library: { type: [ 'image', 'video' ] }, library: { type: 'application/pdf' }, library: { uploadedTo: postId }, and library: { author: MyPluginMedia.currentUserId }.
Localize MyPluginMedia.currentUserId from PHP with get_current_user_id() if you need an author filter. Do not read it from wp.media.view.settings.post.featuredImageId — that value is an attachment/post ID, not a user ID.
The client-side media query layer recognizes a curated set of props (search, type, perPage, menuOrder, uploadedTo, status, include, exclude, author) and maps some of them to query vars such as s. Do not assume arbitrary WP_Query attachment args will work from library.
// Single. The default.\nmultiple: false\n\n// Multi-select with normal toggle behavior (re-clicking deselects).\nmultiple: true\n\n// Multi-select where re-clicking does NOT deselect — useful for \"add to gallery\".\nmultiple: 'add'\nFor multi-select, iterate the selection collection:
\nframe.on( 'select', function () {\n const attachments = frame.state().get( 'selection' ).toJSON();\n attachments.forEach( function ( attachment ) {\n // attachment.id, attachment.url, attachment.title, attachment.sizes, ...\n } );\n} );\nWhen the user already picked an image and reopens the picker, you want that image highlighted in the library — not a blank grid. Hook into open and add the attachment to the selection:
frame.on( 'open', function () {\n const selection = frame.state().get( 'selection' );\n selection.reset();\n\n const currentId = parseInt( $( '#myplugin_logo_id' ).val(), 10 );\n if ( ! currentId ) {\n return;\n }\n const attachment = wp.media.attachment( currentId );\n attachment.fetch(); // hydrate through core's get-attachment AJAX action if not in cache\n selection.add( attachment );\n} );\nwp.media.attachment( id ) returns a Backbone model; .fetch() pulls the data through core's get-attachment admin-ajax action (cached after first call).
selection.first().toJSON()The same shape wp_prepare_attachment_for_js() returns server-side. Useful fields for plugin code:
| Field | \nWhat it is | \n
|---|---|
id | \nAttachment post ID — the value you save | \n
url | \nURL of the ORIGINAL file (full resolution) | \n
title / alt / caption / description | \nUser-facing metadata | \n
mime / type / subtype | \n'image/png' / 'image' / 'png' | \n
filename | \nFile basename | \n
filesizeInBytes / filesizeHumanReadable | \nSize info | \n
width / height | \nDimensions of the original (images/videos only) | \n
sizes | \nMap of exposed image sizes → { url, width, height, orientation, ... }. Core exposes thumbnail, medium, large, and full when metadata exists; custom sizes only appear if they are exposed through image_size_names_choose | \n
link | \nPublic attachment page URL | \n
uploadedTo | \nParent post ID (if attached to a post) | \n
author | \nUser ID who uploaded | \n
The pitfall: attachment.url is ALWAYS the full-size URL. To get a thumbnail, dig into attachment.sizes.thumbnail.url. Production preview code should fall back gracefully (some attachments, especially non-images or SVGs without thumbnails, don't have all sizes registered).
function getDisplayUrl( attachment, sizeName = 'thumbnail' ) {\n if ( attachment.sizes && attachment.sizes[ sizeName ] ) {\n return attachment.sizes[ sizeName ].url;\n }\n if ( attachment.sizes && attachment.sizes.medium ) {\n return attachment.sizes.medium.url;\n }\n return attachment.url; // fallback to original\n}\nUse select for actual picks, open for preselecting an existing attachment, and close only for cleanup or refocusing. Do not save on close; cancellation fires it too. See reference.md for the event table.
WordPress 7.1 enables Media Library infinite scrolling by default, with a\nper-user opt-out and the media_library_infinite_scrolling filter. Do not assume\nall attachments or a final page are already loaded into a frame collection.\nRead reference.md for preference/filter precedence and test implications.
Save the ID, never the URL. Sanitize with absint(), verify that it is an\nattachment of the allowed MIME/type, and enforce the authorization appropriate\nto the setting (for example, whether the current user may use or edit that\nattachment). A post_type = attachment check alone does not establish access\nor image-ness. Render with wp_get_attachment_image() and use\nwp_get_attachment_image_url( $id, $size ) only when you truly need a raw URL.\nSee reference.md for the snippets.
wp_enqueue_media() before any code that touches wp.media. The cause of 90% of \"wp.media is undefined\" reports.attachment.url is the FULL-size URL. Use attachment.sizes.<size>.url for any other size, with a fallback for attachments that don't have that size registered.select, not close. close fires on cancel too — you'll save a phantom value.multiple: 'add' is NOT a typo for true. They're three distinct modes — false (single), true (multi with deselect), 'add' (multi without deselect, the gallery builder mode).DOMContentLoaded. Translations and modal containers may not be ready.wp.media.view.* to build a custom frame unless you've read media-views.js. The Backbone architecture is undocumented in places and changes between WP versions. For 95% of plugin needs, wp.media( { frame, library, multiple } ) is enough.See reference.md for before/after snippets covering implicit wp.media() defaults, saving URLs instead of IDs, missing wp_enqueue_media(), recreating frames on every click, and assuming attachment.sizes.thumbnail always exists.
Use one cached frame, but track the active row before opening it. On select, write the chosen attachment ID into that row's hidden input. See reference.md for the full delegated-click example.
wp-plugin-assets-loading for the $hook_suffix enqueue gate.wp-admin-settings-api when the picker lives inside an options page; the hidden input goes through the sanitize_callback.wp-admin-drag-and-drop when building a gallery with reorderable thumbnails — wp.media gives you the IDs, sortable gives you the order.wp-client-side-media-processing for WordPress 7.1 browser-side image processing and REST finalization; it is separate from selecting an existing attachment.wp.media.view.MediaFrame.Select. Doable but undocumented; almost never needed.wp.customize.MediaControl). Different abstraction layer.wp_handle_upload, media_handle_upload). That's a PHP-side topic.<MediaUpload> from @wordpress/media-utils — that wraps the same Backbone frame but exposes a React-ergonomic API. Out of scope for classic admin pages.wp-includes/media.php — wp_enqueue_media(), wp_prepare_attachment_for_js(), and Media Library settings.wp-includes/js/media-models.js — wp.media() entry point and frame-type switch.wp-includes/js/media-views.js — the Backbone views; useful when you actually need to subclass.wp-includes/script-loader.php — media-editor, media-views, media-models handle registrations.reference.md — server render snippets, event table, per-row picker, and common mistakes.