Title: Media Pair
Author: Bogdan Bendziukov
Published: July 24, 2026
Last modified: July 24, 2026
---
Search plugins
# Media Pair
By [Bogdan Bendziukov](https://profiles.wordpress.org/barb0ss/)
[Download](https://downloads.wordpress.org/plugin/media-pair.1.0.1.zip)
* [Details](https://wordpress.org/plugins/media-pair/#description)
* [Reviews](https://wordpress.org/plugins/media-pair/#reviews)
* [Installation](https://wordpress.org/plugins/media-pair/#installation)
* [Development](https://wordpress.org/plugins/media-pair/#developers)
[Support](https://wordpress.org/support/plugin/media-pair/)
## Description
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 `
` markup across blocks, featured images, and theme image functions.
* Mobile image pairing in the Media Library, block editor, and media list
* Automatic `` 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 `` element:
* A `` tag serves the mobile image at or below your configured breakpoint.
* The original desktop `` 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 `` 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 `` 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.
## Screenshots
[⌊Media Library attachment details⌉⌊Media Library attachment details⌉[
Media Library attachment details
[⌊Media Library list view⌉⌊Media Library list view⌉[
Media Library list view
[⌊Settings => Media Pair⌉⌊Settings => Media Pair⌉[
Settings => Media Pair
[⌊Block editor sidebar⌉⌊Block editor sidebar⌉[
Block editor sidebar
[⌊Frontend responsive output⌉⌊Frontend responsive output⌉[
Frontend responsive output
## Installation
1. Upload the `media-pair` folder to `/wp-content/plugins/`
2. Activate the plugin through the Plugins screen
3. Open any image in the Media Library and choose a Mobile image
4. Adjust settings under Settings Media Pair
## FAQ
### Does this work with Elementor and other page builders?
Core WordPress image filters cover many cases, but page builders that render images
outside WordPress attachment APIs — including Elementor widgets — may not pick up
paired output. Test your specific layout after pairing.
### I paired an image but nothing changed on the frontend. What should I check?
Confirm that **Enable Media Pair** is turned on under Settings Media Pair, that
the desktop image has a saved mobile pair in the Media Library, and that the frontend
actually uses that attachment (not a hard-coded URL or external image). Clear any
page, CDN, or browser cache and retest at a viewport below your breakpoint.
### Can I use the same file for desktop and mobile?
No. Media Pair is built for art direction — a separate mobile composition cropped
or designed for smaller screens. The plugin requires a different attachment for
the mobile variant.
### Do I need to configure every post or block separately?
No. Pairing is stored on the attachment itself. Once saved in the Media Library,
every use of that image across your site can output the paired markup automatically.
## Reviews
There are no reviews for this plugin.
## Contributors & Developers
“Media Pair” is open source software. The following people have contributed to this
plugin.
Contributors
* [ Bogdan Bendziukov ](https://profiles.wordpress.org/barb0ss/)
[Translate “Media Pair” into your language.](https://translate.wordpress.org/projects/wp-plugins/media-pair)
### Interested in development?
[Browse the code](https://plugins.trac.wordpress.org/browser/media-pair/), check
out the [SVN repository](https://plugins.svn.wordpress.org/media-pair/), or subscribe
to the [development log](https://plugins.trac.wordpress.org/log/media-pair/) by
[RSS](https://plugins.trac.wordpress.org/log/media-pair/?limit=100&mode=stop_on_copy&format=rss).
## Changelog
#### 1.0.1
* Security: escape admin UI output with native WordPress functions
* Security: avoid unverified request input when detecting the attachment edit screen
#### 1.0.0
* Initial release
## Meta
* Version **1.0.1**
* Last updated **1 day ago**
* Active installations **Fewer than 10**
* WordPress version ** 6.0 or higher **
* Tested up to **7.0.2**
* PHP version ** 8.1 or higher **
* Tags
* [art-direction](https://wordpress.org/plugins/tags/art-direction/)[images](https://wordpress.org/plugins/tags/images/)
[mobile](https://wordpress.org/plugins/tags/mobile/)[picture](https://wordpress.org/plugins/tags/picture/)
[responsive](https://wordpress.org/plugins/tags/responsive/)
* [Advanced View](https://wordpress.org/plugins/media-pair/advanced/)
## Ratings
No reviews have been submitted yet.
[Your review](https://wordpress.org/support/plugin/media-pair/reviews/#new-post)
[See all reviews](https://wordpress.org/support/plugin/media-pair/reviews/)
## Contributors
* [ Bogdan Bendziukov ](https://profiles.wordpress.org/barb0ss/)
## Support
Got something to say? Need help?
[View support forum](https://wordpress.org/support/plugin/media-pair/)