{"id":17481199,"url":"https://github.com/paratron/smartimages","last_synced_at":"2025-04-22T13:20:51.092Z","repository":{"id":141688315,"uuid":"73489377","full_name":"Paratron/smartimages","owner":"Paratron","description":"This javascript library makes the images in your website smarter.","archived":false,"fork":false,"pushed_at":"2017-04-11T19:27:59.000Z","size":40,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-19T01:18:40.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Paratron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-11T15:35:28.000Z","updated_at":"2022-11-26T07:22:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"5d004799-9c53-4540-be75-a743ed42ab7f","html_url":"https://github.com/Paratron/smartimages","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Fsmartimages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Fsmartimages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Fsmartimages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Fsmartimages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Paratron","download_url":"https://codeload.github.com/Paratron/smartimages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250246746,"owners_count":21398919,"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":[],"created_at":"2024-10-18T22:08:52.428Z","updated_at":"2025-04-22T13:20:51.041Z","avatar_url":"https://github.com/Paratron.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"SmartImages\n===========\n\nThis javascript library makes images in your website smarter. It enables you to define different source URLs\nfor desktop and mobile devices and even differentiate between regular and retina displays.\n\nSmartImages also brings a basic lazy loading functionality that helps reducing the initial load impact of your website.\n\nThis library has absolutely no dependencies and weights about 1000 bytes if delivered with gzip compression.\n\nYou can find a test/demo document, [here](https://wearekiss.com/lab/smartImages/test/).\n\n## How it works for image elements\nTo make use of the smart loading behaviour, you need to leave the `src` property of your image empty. This way you\nare preventing the browser from directly starting to download the image contents upon pageload.\n\nYou can define up to four image sources on your image tag like so:\n\n````html\n\u003cimg\n\tdata-src=\"regularDesktopImage.jpg\"\n\tdata-src-2x=\"retinaDesktopImage.jpg\"\n\tdata-src-mobile=\"regularMobileImage.jpg\"\n\tdata-src-mobile-2x=\"retinaMobileImage.jpg\"\n\t\u003e\n````\n\nNote how the `src` property is completely omitted here so the browser won't download anything by himself.\n\nYou can simply include the SmartImages library at the bottom of the page and forget about it. \nYou don't need any more configuration:\n   \n````html\n\u003cscript type=\"text/javascript\" src=\"smartImages.min.js\"\u003e\u003c/script\u003e\n````\n\nThe library will check the browser and then apply the needed image sources for the current environment.\n\nIt decides what to use based on two media queries. A device is detected as a retina device, when\nthe minimal device pixel ratio is 1.25 or the resolution is more then 120 dpi.\n\nIf a device is considered \"mobile\" will be detected by the media query `(max-width: 650px)`. This can be changed\nmanually, if desired.\n\nHeads up: SmartImages will dynamically swap image sources when you resize the browser window\nand cross the border defined in the media query.\n\nIf you want certain images to be ignored by the lib, simply add the `data-smart-ignore` attribute to the image tag\nand SmartImages will _not_ replace the sources automatically, even if data-src definitions are present.    \nYou only need to apply this to images where you have defined `data-src...` attributes but want the library to leave them alone.\n\n## How it works for containers\nThe library supports smart background image loading since version 2.3. The functionality behaves very much like with\nthe image tags - the only difference is that you need to additionally apply the attribute `data-smartImageContainer`\nto any containers that should be recognized by the library.\n\n````html\n\u003cdiv\n\tdata-smartImageContainer\n\tdata-src=\"regularDesktopImage.jpg\"\n\tdata-src-2x=\"retinaDesktopImage.jpg\"\n\tdata-src-mobile=\"regularMobileImage.jpg\"\n\tdata-src-mobile-2x=\"retinaMobileImage.jpg\"\n\t\u003e\n\t\u003c!-- Some other HTML stuff in here --\u003e\n\u003c/div\u003e\n````\n\nLazy loading is also supported for container backgrounds.\n\nInstead of just defining an image URL, you can put everything into the src attributes that would be a [valid css `background-image` value](https://developer.mozilla.org/en/docs/Web/CSS/background-image).\nThis is especially handy when you want to define multiple background images.\n\n\n## Using the lazy loader\nSometimes you want to reduce the initial loading impact of your website - especially when\n its using a LOT of image data. You can do so by applying the attribute `data-lazy` to your\n images. When the attribute is present, SmartImages will only start to download the images\n when they get near the viewport of the browser. Rule of thumb: everything below\n scrollPos + (screenHeight * 1.5) is not downloaded yet.\n \n### Preserving the layout with lazy images\nIf you leave the `src` attribute of your image tags empty, they will collapse and can possibly mess up your\n document layout. Not only would every freshly loaded lazy image cause your document to re-align and completely redrawn,\n it will also mess with the lazy loading functionality itself, since the lazy loader looks for the positions of the images\n in the document. If they all collapse, it is very well possible that the lazy loader will fetch all of them upon page request - \n thats really not a desired behaviour.\n \nYou can tell the library about the dimensions of the images to be expected if they are requested. The library will then\n go ahead and dynamically create an empty, transparent dummy image and use it as a replacement source until you load the real\n  image from the server. This will cause your layout to be correctly calculated and nothing will jump around when the lazy images\n   are requested from the server.\n   \nYou can tell the SmartImages library about image sizes like this:\n\n````html\n\u003cimg\n\tdata-lazy\n\t\n\tdata-src=\"regularDesktopImage.jpg\"\n\tdata-size=\"1200x800\"\n\t\n\tdata-src-2x=\"retinaDesktopImage.jpg\"\n\tdata-size-2x=\"2400x1600\"\n\t\n\tdata-src-mobile=\"regularMobileImage.jpg\"\n\tdata-size-mobile=\"320x213\"\n\t\n\tdata-src-mobile-2x=\"retinaMobileImage.jpg\"\n\tdata-size-mobile-2x=\"640x426\"\n\t\u003e\n````\n\nThis works for container backgrounds as well but is probably not as important there, because background images don't interfer\nwith container dimensions.\n\n  \n## Intercepting initialization\nBy default, SmartImages listens to the body.load event and will initialize when everything\nelse on your page has been loaded. You can disable that behaviour.\n\nWhen you call `smartImages.noAutoInit()` right after you embedded the library in your\npage, SmartImages won't initialize itself. You need to call `smartImages.init()` manually.\n\nI've implemented this because I had pages where I definitely only wanted to load ONE big\nimage above the fold first and nothing else.\n\nThis can be done by including the library, disabling the autoInit and then applying\nthe SmartImage functionality manually on just one image. After that image has been loaded,\ninitialize the library as usual.\n\nHere's an example:\n\n````html\n\u003cscript type=\"text/javascript\" src=\"smartImages.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\tsmartImages.noAutoInit();\n\u003c/script\u003e\n\n\u003cimg\n\tdata-src=\"myHeaderImage.jpg\"\n\tdata-src-2x=\"myHeaderImage_2x.jpg\"\n\tdata-src-mobile=\"myHeaderImageMobile.jpg\"\n\tdata-src-mobile-2x=\"myHeaderImageMobile_2x.jpg\"\n\tonload=\"smartImages.init\"\n\tid=\"myHeaderImage\"\n\t\u003e\n\t\n\u003cscript\u003e\n\tsmartImages.manualAssign(document.getElementById('myHeaderImage'));\n\u003c/script\u003e\n````\n\nNotice how I applied the `init()` method to the `onload` event of the image.\n\n## Custom methods\n\nYou can use the method `smartImages.manualAssign(domElement)` to manually assign the source/background of an image or container once.\n\nThere is also a method `smartImages.getSrc(domElement)` that will just return the source, SmartImages would select\nin the very moment and returns it as a string. For containers, use the method `smartImages.getBackground(domElement)`.\n\n## Custom media query and source\n\nSince version 2.4, you can define a custom media query for images and containers to be matched.\n\nBe careful: a custom query will always override other decisions of the library, if it matches.\n\nTo use a custom query, simply add the following attributes to your image or container:\n\n````html\n\u003cimg\n\tdata-src-custom=\"myCustomImage.jpg\"\n\tdata-match-custom=\"(min-width: 650px) and (max-width: 1400px)\"\n\tdata-size-custom=\"1400x200\"\n\u003e\n````\n\nThe size attribute is optional, as usual.\n\n## Usage on non-image DOM nodes\nNormally, smartImages will only process image tags. If you apply the `data-smartImageContainer` attribute to a container,\nsmartImages will manage the background image styles of that container.\n\nSince version 2.5.0, you can force smartImages to apply its functionality to any other DOM node, even if its not an image by\nadding the attribute `data-smartEntity`.\n\nThis means, you can for example lazy load an embedded google map inside of an iframe:\n\n````html\n\u003ciframe\n\tstyle=\"width: 100%;height: 500px;border: none;\"\n\tdata-smartEntity\n\tdata-lazy\n\tdata-src=\"https://www.google.com/maps/embed?pb=!1m14!1m12!1m3!1d163720.5843738355!2d8.6365638!3d50.121212!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!5e0!3m2!1sde!2sde!4v1486502861858\"\u003e\u003c/iframe\u003e\n````\n\nYou could even load a different source into the iframe depending on the viewport size - but we're drifting off, here ;)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparatron%2Fsmartimages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparatron%2Fsmartimages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparatron%2Fsmartimages/lists"}