wp-admin-media-frame

WordPress Admin Media Picker (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.

When to use this skill

Trigger when ANY of the following is true:

• A plugin admin page needs to pick an image / file / video / audio from the WP Media Library.
• The user is adding a "Choose image", "Upload logo", "Select gallery", "Pick avatar", "Browse media" button to a settings page, metabox, or repeater row.
• Code references wp.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.
• The user has a textarea / hidden input for an attachment ID and needs the UI around it.
• The user complains: "wp.media is undefined", "the modal opens but the Select button does nothing", "I get the URL but not the right size".

The bootstrap — three pieces

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.

1. PHP — call wp_enqueue_media() on YOUR screen only

wp_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 {
    if ( 'settings_page_myplugin' !== $hook_suffix ) {
        return;
    }

    wp_enqueue_media();

    wp_enqueue_script(
        'myplugin-media-picker',
        plugins_url( 'assets/media-picker.js', MYPLUGIN_FILE ),
        array( 'jquery', 'media-editor', 'wp-i18n' ),
        MYPLUGIN_VERSION,
        array( 'in_footer' => true )
    );
} );