Media Pair

Media Pair adds art direction to WordPress Media Library images. Upload a desktop image, pair a separate mobile composition once, and the plugin outputs semantic <picture> markup across blocks, featured images, and theme image functions.

• Mobile image pairing in the Media Library, block editor, and media list
• Automatic <picture> output via core WordPress filters
• Support for Image, Featured Image, Gallery, and Media & Text blocks
• Inline content images via wp_content_img_tag
• Global breakpoint and enable/disable settings
• Admin hints in the Media Library, featured image metabox, and block editor
• media_pair_get_picture() helper for themes and ACF blocks

How it works

Media Pair stores a link between a desktop attachment and a separate mobile attachment. When WordPress renders the desktop image on the frontend, the plugin wraps it in a <picture> element:

• A <source> tag serves the mobile image at or below your configured breakpoint.
• The original desktop <img> remains as the fallback for larger screens.

Pairing happens once per image in the Media Library. You do not need to configure individual posts, blocks, or pages. Anywhere WordPress outputs that attachment — featured images, Image blocks, galleries, theme templates, or custom code using wp_get_attachment_image() — the paired markup is applied automatically.

The frontend uses pure HTML and CSS media queries. No JavaScript is loaded for visitors.

Configuration

Pairing images

1. Open Media → Library and select a desktop image.
2. In the attachment details, find the Mobile image field.
3. Click Select, choose a separate mobile composition from the library, and save.
4. The pair saves automatically. Use Remove to unlink the mobile image.

You can also manage pairs from:

• The Mobile pair column in the Media Library list (includes a filter for paired/unpaired images)
• The Media Pair panel in the block editor sidebar for Image and Featured Image blocks
• A hint in the post Featured image metabox when the selected image has an active pair

Each mobile image can only be linked to one desktop image. An image already used as someone else’s mobile variant cannot be given its own pair.

Plugin settings

Go to Settings → Media Pair:

• Enable Media Pair — Turn frontend <picture> output on or off globally.
• Mobile breakpoint (px) — Screen width at which the mobile image is used. Default: 767. Screens at or below this width load the mobile source.
• Picture CSS class — CSS class added to generated <picture> elements. Default: media-pair.
• Data cleanup — When enabled, all pairing metadata is removed if you uninstall the plugin.

Where output appears

Media Pair hooks into standard WordPress image rendering:

• wp_get_attachment_image() — theme templates, widgets, and custom code
• post_thumbnail_html — featured images
• wp_content_img_tag — inline images in post and block content, including Image, Gallery, and Media & Text blocks

Images without a mobile pair are left unchanged.

For developers

Use media_pair_get_picture( $attachment_id, $size, $attr, $context ) in themes or ACF blocks when you need explicit control over picture output.

Use the media_pair_should_use_pair filter to allow or skip pairing for specific attachments or render contexts.

Privacy

Media Pair does not send data to external services and does not track users.