{"id":13759986,"url":"https://github.com/justcoded/just-responsive-images","last_synced_at":"2025-10-31T09:31:02.795Z","repository":{"id":47256960,"uuid":"83833992","full_name":"justcoded/just-responsive-images","owner":"justcoded","description":"WordPress Plugin to support better responsive images with \u003cpicture\u003e tag, backgrounds, retina support etc.","archived":false,"fork":false,"pushed_at":"2021-09-06T13:15:02.000Z","size":489,"stargazers_count":48,"open_issues_count":8,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-02-14T10:01:54.297Z","etag":null,"topics":["oop-principles","php","responsive","responsive-design","responsive-images","retina","wordpress","wordpress-development","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justcoded.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-03T19:32:08.000Z","updated_at":"2024-10-08T14:33:47.000Z","dependencies_parsed_at":"2022-09-02T00:10:43.982Z","dependency_job_id":null,"html_url":"https://github.com/justcoded/just-responsive-images","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fjust-responsive-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fjust-responsive-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fjust-responsive-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fjust-responsive-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justcoded","download_url":"https://codeload.github.com/justcoded/just-responsive-images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239166926,"owners_count":19593110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oop-principles","php","responsive","responsive-design","responsive-images","retina","wordpress","wordpress-development","wordpress-plugin"],"created_at":"2024-08-03T13:01:01.857Z","updated_at":"2025-10-31T09:30:57.398Z","avatar_url":"https://github.com/justcoded.png","language":"PHP","readme":"# Just Responsive Images \n### WordPress plugin \n\n\nThe Just Responsive Images plugin gives you control of responsive image properties, which WordPress 4.4+ \ninserts to all post thumbnails by default.\n\nThe default solution is to insert all available image sizes as srcset attribute into img tag. \nThis is not optimal, because the browser gets too much image resolutions, it can generate more requests to \nthe server (to get the right image) and it takes longer to display the image itself. Not to mention, Google \nPage Speed inspector is not satisfied with such a method.\n\nIf you have hand-coded a mobile-friendly HTML/CSS for your theme it usually has media queries for background \nimages and \\\u003cpicture\\\u003e tags instead of \\\u003cimg\\\u003e tags. A lot of images are used as block backgrounds very often, \nwhich should be editable from CMS. All these best practices are not supported in the WordPress core by default \nand you end up wasting your time re-writing standard functions.\n\nThat's why we're here! We want to provide easy-to-use control for customizing srcset for each image size \ndimension you use inside your theme. Also we're happy to provide you with a few helpers which will generate \ntags and generate required media queries for backgrounds.\n\n\n## Installation\n\n1. Download, unzip and upload to your WordPress plugins directory\n2. Activate the plugin within you WordPress Administration Backend\n\n## Register configuration hook\n\nTo set configuration options you should create a new function and register a new filter hook `rwd_image_sizes` inside your `functions.php` file:\n\n\tadd_filter('rwd_image_sizes', 'my_rwd_image_sizes');\n\tfunction my_rwd_image_sizes( $image_sizes ) {\n\t\t$my_image_sizes = array( ... );\n\t\treturn $my_image_sizes;\n\t}\n\nIf you have complex sizes with a lot of different image sizes - we recommend using a separate file to store settings. \nIn this case, load function will look like this:\n\n\tadd_filter('rwd_image_sizes', 'my_rwd_image_sizes');\n\tfunction my_rwd_image_sizes( $image_sizes ) {\n\t\treturn include get_stylesheet_directory() . '/rwd-image-sizes.php';\n\t}\n\nAfter that you need to create a new file called `rwd-image-sizes.php` and set a configuration array there.\n\n## Configuration array\n\nHere comes the most important part, you need to configure it very carefully. I will try to explain how to create \nthis array step-by-step.\n\nConfiguration array is an associative multidimensional array.\n\n_*All examples is based on a second option of configuration settings - as a separate configuration file._\n\n#### Main image sizes\n\nThe first level indicates the main image sizes, which should be registered with the Wordpress `add_image_size()` \nfunction. We recommend re-writing standard sizes as well, like thumbnail, medium, and large. \nEach main size should be an array as well, so it looks like this:\n\n\n\t\u003c?php\n\treturn array(\n\t\t'thumbnail' =\u003e array( ... ),\n\t\t'medium' =\u003e array( ... ),\n\t\t'large' =\u003e array( ... ),\n\t\t'hd' =\u003e array( ... ),\n\t);\n\nIn this example we overwrite the 3 standard WordPress sizes: thumbnail, medium and large, \nand register a new one called 'hd'.\n\n#### Single image size\n\nFor small images you don't need to add any responsive tags, because they are smaller than any screen size \n(even mobile). For example, you have post featured image displayed on a blog listing in a 250 x 200 size .\n\nIn this case you should specify the size array under your main image size:\n \n\t\u003c?php\n\treturn array(\n\t\t'thumbnail' =\u003e array(\n\t\t\tarray( 250, 200, true ), // single size, dimensions set here\n\t\t),\n\t\t...\n\t);\n\t\nThe dimensions array looks the same as parameters passed to the WordPress `add_image_size()` function. function. So they are:\n\n* width, integer\n* height, integer\n* crop, true|false|array, which set crop position\n\n#### Nested sizes\n\nLet's imagine a more complex example. You have a full-width visual image at the top of your single post. \nFor desktop versions you will use a 1920px or even 2400px image. However, if you use a phone to browse the site, \nthe user doesn't like to wait while such big images load because what he sees is 320-400px on his screen. \nSo we need to set, that for big visual images we should use smaller versions on smaller resolutions.\n\nHere we will use a more complex configuration. Now all arrays inside the main size will be much more complex \nand will have a special structure like this:\n\n\t\u003c?php \n\treturn array(\n\t\t'visual' =\u003e array(\n\t\t\tarray(\n\t\t\t\tarray( 1920, 500, true ),\n\t\t\t\t// responsive options:\n\t\t\t\t...\n\t\t\t),\n\t\t\t'tablet' =\u003e array(\n\t\t\t\tarray( 1024, 300, true ),\n\t\t\t\t// responsive options:\n\t\t\t\t...\n\t\t\t),\n\t\t\t'mobile' =\u003e array(\n\t\t\t\tarray( 414, 200, true ),\n\t\t\t\t// responsive options:\n\t\t\t\t...\n\t\t\t),\n\t\t),\n\t);\n\nAs you can see here we registered a new image size \"visual\" with the size of 1920x500px, and it has lower resolutions \nwhich has it’s own name:\n\n* 1024x300 (the full qualified name will be \"visual-tablet\")\n* 414x200 (the full qualified name will be \"visual-mobile\")\n\nIn addition, each size has to have responsive options.\n\n#### Responsive options\n\nThese are options, which will be used to generate \\\u003cpicture\\\u003e, \\\u003cimg\\\u003e or background HTML/CSS.\n\nLet's start with an example:\n \n\treturn array(\n    \t'visual' =\u003e array(\n    \t\tarray(\n    \t\t\tarray( 1920, 500, true ),\n    \t\t\t'picture' =\u003e '\u003csource srcset=\"{src}\" media=\"(min-width: 1281px)\"\u003e',\n    \t\t\t'bg' =\u003e '', // main image, no media wrapper will be used.\n    \t\t\t'srcset' =\u003e '1920w', // descriptor\n    \t\t\t'sizes' =\u003e '(min-width: 1281px) 1920px', // condition\n    \t\t),\n    \t\t'tablet' =\u003e array(\n    \t\t\tarray( 980, 9999 ),\n    \t\t\t'picture' =\u003e '\u003cimg src=\"{single-src}\" srcset=\"{src}\" alt=\"{alt}\"\u003e',,\n    \t\t\t'bg' =\u003e '@media screen and (max-width:980px)',\n    \t\t\t'srcset' =\u003e '980w',\n    \t\t\t'sizes' =\u003e '(min-width: 415px) 980px',\n    \t\t),\n    \t),\n    );\n\nFor each image size you can specify any of the following 4 keys:\n\n* `picture` -  a code part to generate \\\u003csource\\\u003e or \\\u003cimg\\\u003e tags inside a \\\u003cpicture\\\u003e tag. \n* `bg` - media query to be used to wrap the css selector. Keep blank to set default image here.\n* `srcset` - \\\u003cimg\\\u003e attribute part - width descriptor for this image size. \n* `sizes`  - \\\u003cimg\\\u003e attribute part - condition when current dimension should be visible.\n\nIf you use only one way to print your image (for example \\\u003cpicture\\\u003e  tag) - you can skip all other parts and \nset only 1 key `picture` inside responsive options.\n\n#### Re-usable sizes\n\nSome images can have similar small sizes inside. In this case you can use previously defined keys inside other\nmain sizes. Imagine that we already have the code for \"visual\" image size, as shown above, then we can re-use \nit like this:\n\n\treturn array(\n\t\t'visual' =\u003e array( ... ),\n\t\t'big-banner' =\u003e array(\n\t\t\tarray(\n\t\t\t\tarray( 2400, 500, true ),\n\t\t\t\t'picture' =\u003e '\u003csource srcset=\"{src}\" media=\"(min-width: 1281px)\"\u003e',\n\t\t\t\t'bg' =\u003e '', // main image, no media wrapper will be used.\n\t\t\t\t'srcset' =\u003e '1920w', // descriptor\n\t\t\t\t'sizes' =\u003e '(min-width: 1281px) 1920px', // condition\n\t\t\t),\n\t\t\t'visual-tablet' =\u003e 'inherit',\n\t\t),\n\t);\n\t\n#### Retina support\n\t\nTo support retina screens and print both usual and bigger images \n\tyou should add retina multiplier to your size name, separated with a space:\n\n\treturn array(\n\t\t'visual 2x' =\u003e array( ... ),\n\t);\n\nYou can add more different multipliers for same size to generate even more retina sizes:\n\n\treturn array(\n\t\t'visual 2x 3x' =\u003e array( ... ),\n\t);\n\nHowever we recommend to use one retina size - `2x`, this size provides good visual image quality on screen and keep your file space less \n(comparing to setting several retina multipliers).\n\n##### Retina background @media queries\n\nBy default plugin search such patterns inside `'bg'` property: \n\t\n\t(min-width: XXXpx) or (max-width: XXXpx)\n\t\nIf such entries found, then plugin replace them with the structure below to generate @media retina query:\n \n \t(min-width: XXXpx) and \u003cmin device pixel ratio query\u003e, (min-width: XXXpx) and \u003cmin resolution query\u003e\n \t \nIf you want to set your own specific media query for retina size you can use `'bg_retina'` property like this:\n\n\treturn array(\n\t\t'big-banner 2x' =\u003e array(\n\t\t\tarray(\n\t\t\t\tarray( 2400, 500, true ),\n\t\t\t\t...\n\t\t\t\t'bg' =\u003e '@media (min-width:1281px)',\n\t\t\t\t'bg_retina' =\u003e '@media (min-width:1281px) and {dpr}, (min-width:1281px) and {min_res}',\n\t\t\t\t...\n\t\t\t),\n\t\t\t...\n\t\t),\n\t);\n\nSpecial tokens `{dpr}` and `{min_res}` will be automatically replaced with a corresponding min device pixel ratio\n\tand min resolution values based on retina multiplier (2x or 3x).\n\t\n#### Pre-defined RWD set\n\nThe plugin has its own set of rwd styles, which are optimal for big images display and resize them to smaller \nresolutions, which passed Google Page Speed tests well. This set has retina 2x support by default.\n\nIt looks like this:\n\n\treturn array(\n\t\t'rwd 2x' =\u003e array(\n\t\t\t'desktop' =\u003e array(\n\t\t\t\tarray( 1920, 9999 ),\n\t\t\t\t'picture' =\u003e '\u003csource srcset=\"{src}\" media=\"(min-width: 1281px)\"\u003e',\n\t\t\t\t'bg' =\u003e '@media (min-width:1281px)',\n\t\t\t\t'bg_retina' =\u003e '@media (min-width:1281px) and {dpr}, (min-width:1281px) and {min_res}',\n\t\t\t\t'srcset' =\u003e '{w}w',\n\t\t\t\t'sizes' =\u003e '(min-width: 1281px) {w}px',\n\t\t\t),\n\t\t\t'laptop' =\u003e array(\n\t\t\t\tarray( 1280, 9999 ),\n\t\t\t\t'picture' =\u003e '\u003csource srcset=\"{src}\" media=\"(min-width: 981px)\"\u003e',\n\t\t\t\t'bg' =\u003e '@media (min-width: 981px) ',\n\t\t\t\t'bg_retina' =\u003e '@media (min-width: 981px) and {dpr}, (min-width: 981px) and {min_res}',\n\t\t\t\t'srcset' =\u003e '{w}w',\n\t\t\t\t'sizes' =\u003e '(min-width: 981px) {w}px',\n\t\t\t),\n\t\t\t'tablet' =\u003e array(\n\t\t\t\tarray( 980, 9999 ),\n\t\t\t\t'picture' =\u003e '\u003csource srcset=\"{src}\" media=\"(min-width: 415px)\"\u003e',\n\t\t\t\t'bg' =\u003e '@media (min-width: 415px)',\n\t\t\t\t'bg_retina' =\u003e '@media (min-width: 415px) and {dpr}, (min-width: 415px) and {min_res}',\n\t\t\t\t'srcset' =\u003e '{w}w',\n\t\t\t\t'sizes' =\u003e '(min-width: 415px) {w}px',\n\t\t\t),\n\t\t\t'mobile' =\u003e array(\n\t\t\t\tarray( 414, 9999 ),\n\t\t\t\t'picture' =\u003e '\u003cimg src=\"{single-src}\" srcset=\"{src}\" alt=\"{alt}\"\u003e', // mobile-first strategy picture img.\n\t\t\t\t'bg' =\u003e '',                                                 // mobile-first strategy bg.\n\t\t\t\t'bg_retina' =\u003e '@media {dpr}, {min_res}',\n\t\t\t\t'srcset' =\u003e '{w}w',\n\t\t\t\t'sizes' =\u003e '{w}px',\n\t\t\t),\n\t\t),\n\t);\n\t\nYou can use these presets inside your own styles.\n\n## Template functions\n\nWe have 3 new template functions:\n\n### rwd_attachment_image\n\n`rwd_attachment_image( $attachment = null, $size = 'thumbnail', $tag = 'picture', $attr = array() )`\n\n- WP_Post|int|null **$attachment** Atatchment object, Attachment ID or null. In case of null the function will search current post featured image.\n- string|array **$size** Image size name or array of sizes. We will check this option in more details below.\n- string **$tag** Available options are 'picture' and 'img'. The html tag, which will be used for image generation.\n- array **$attr** Additional html attributes to be used for main tag (for example \"class\", \"id\", etc.).\n\n**$size** option as array:\n\nSometimes mobile images are different from desktop images and there is a need to use another attachment image for \nsmaller sizes. To support this feature you can pass array here and specify which size use another attachment ID\nor object.\n\nLet's check the example:\n\n\trwd_attachment_image( $featured_image_id, array(\n\t\t\t'visual', // main size, which should be rendered; it should has a zero key!\n\t\t\t'mobile' =\u003e $mobile_image_id, // rewrite a key under 'visual' main size to use another image \n\t));\n\t\n**Important**: If you use retina multipliers we do not recommend to use `'img'` tag with sized array. \nIn this case browser will automatically decide which image will be renedered and you won't get the same \nimages on specific resolution in all browsers/devices.\n\n\t\n### rwd_attachment_background\n\t\n`rwd_attachment_background( $selector, $attachment = null, $size = 'thumbnail' )`\t\n\n- string **selector** CSS selector to be used inside inline styles code.\n- WP_Post|int|null **$attachment** Atatchment object, Attachment ID or null. In case of null the function will search current post featured image.\n- string|array **$size** Image size name or array of sizes. Same as for `rwd_attachment_image()`.\n\nThis function generate css styles and place them inside \"buffer\". This buffer will be printed in wp_footer().\n\nIf you want to print it earlier you can use next template function:\n\n### rwd_print_styles\n\n`rwd_print_styles()`\n\nThis function print styles from buffer, which were generated in `rwd_attachment_background()`.\n\n## Generated code samples\n\nIt can generate code similar to this one:\n\n**picture**\n\n\t\u003cpicture\u003e\n\t\t\u003csource srcset=\"image-desktop.jpg, image-desktop-2x.jpg 2x\" media=\"(min-width: 1281px)\"\u003e\u003c!-- 1920px image!--\u003e\n\t\t\u003csource srcset=\"image-landscape.jpg, image-landscape-2x.jpg 2x\" media=\"(min-width: 981px)\"\u003e\u003c!-- 1280px !--\u003e\n\t\t\u003csource srcset=\"image-tablet.jpg, image-tablet-2x.jpg 2x\" media=\"(min-width: 415px)\"\u003e\u003c!-- 980px image!--\u003e\n\t\t\u003cimg srcset=\"image-mobile.jpg, image-mobile-2x.jpg 2x\" alt=\"test\"\u003e \u003c!-- 414px image!--\u003e\n\t\u003c/picture\u003e\n\t\n**img**\n\t\n\t\u003cimg sizes=\"(min-width: 1281px) 1920px, (min-width: 981px) 1280px, (min-width: 415px) 980px, 414px\"\n         srcset=\"examples/images/medium.jpg 414w,\n         examples/images/medium-2x.jpg 828w,\n         examples/images/large.jpg 980w,\n         examples/images/large-2x.jpg 1960w,\n         examples/images/extralarge.jpg 1280w,\n         examples/images/extralarge-2x.jpg 2560w,\n         examples/images/desctop.jpg 1920w,\n         examples/images/desctop-2x.jpg 3840w\" alt=\"...\"\u003e\n         \n**background**\n    \n    \u003cstyle type=\"text/css\"\u003e\n    \t/* rwd-background-styles */\n    \t.article-bg {\n    \t\tbackground-image: url('images/bg-mobile.jpg');\n    \t}\n    \t@media (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {\n    \t\t.article-bg {\n    \t\t\tbackground-image: url('images/bg-mobile-2x.jpg');\n    \t\t}\n    \t}\n    \t@media (min-width: 415px) {\n    \t\t.article-bg {\n    \t\t\tbackground-image: url('images/bg-tablet.jpg');\n    \t\t}\n    \t}\n    \t@media (min-width: 415px) and (-webkit-min-device-pixel-ratio: 1.5), (min-width: 415px) and (min-resolution: 144dpi) {\n    \t\t.article-bg {\n    \t\t\tbackground-image: url('images/bg-tablet-2x.jpg');\n    \t\t}\n    \t}\n    \t@media (min-width: 981px) {\n    \t\t.article-bg {\n    \t\t\tbackground-image: url('images/bg-laptop.jpg');\n    \t\t}\n    \t}\n    \t@media (min-width: 981px) and (-webkit-min-device-pixel-ratio: 1.5), (min-width: 981px) and (min-resolution: 144dpi) {\n    \t\t.article-bg {\n    \t\t\tbackground-image: url('images/bg-laptop-2x.jpg');\n    \t\t}\n    \t}\n    \u003c/style\u003e \n","funding_links":[],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustcoded%2Fjust-responsive-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustcoded%2Fjust-responsive-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustcoded%2Fjust-responsive-images/lists"}