{"id":15016600,"url":"https://github.com/5t3ph/eleventy-plugin-objectfit-focalpoint","last_synced_at":"2025-04-12T10:13:11.277Z","repository":{"id":57093420,"uuid":"393228416","full_name":"5t3ph/eleventy-plugin-objectfit-focalpoint","owner":"5t3ph","description":null,"archived":false,"fork":false,"pushed_at":"2021-08-07T02:25:48.000Z","size":293,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T10:13:03.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/5t3ph.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":"2021-08-06T02:47:18.000Z","updated_at":"2025-01-09T09:52:00.000Z","dependencies_parsed_at":"2022-08-22T20:40:34.919Z","dependency_job_id":null,"html_url":"https://github.com/5t3ph/eleventy-plugin-objectfit-focalpoint","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"5t3ph/eleventy-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5t3ph%2Feleventy-plugin-objectfit-focalpoint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5t3ph%2Feleventy-plugin-objectfit-focalpoint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5t3ph%2Feleventy-plugin-objectfit-focalpoint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5t3ph%2Feleventy-plugin-objectfit-focalpoint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5t3ph","download_url":"https://codeload.github.com/5t3ph/eleventy-plugin-objectfit-focalpoint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248550633,"owners_count":21122934,"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-09-24T19:49:07.723Z","updated_at":"2025-04-12T10:13:11.244Z","avatar_url":"https://github.com/5t3ph.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Eleventy Plugin: Object-Fit Focal Point\n\n\u003e An Eleventy Nunjucks shortcode to provide the functionality of generating an image's `object-position` value in order to keep the focal point in view. [Test drive the results by using the utilty app](https://objectfit-focalpoint.netlify.app/).\n\nThis shortcode works in combination with the CSS property `object-fit` which makes an `img` act as it's own container. When assigned the value of `cover`, the image behaves similar to `background-size: cover`.\n\n**Unfamilar with `object-fit`?** [Check out my 2 minute free egghead video \u003e](https://egghead.io/lessons/css-apply-aspect-ratio-sizing-to-images-with-css-object-fit?af=2s65ms)\n\nThe shortcode uses the [sharp package resize API](https://sharp.pixelplumbing.com/api-resize) to determine the focal point of an image with [Shannon entropy](https://en.wikipedia.org/wiki/Entropy_%28information_theory%29). It then applies the calculated point as a percentage based on the image's aspect ratio as the value of `object-position`. **When your image container is resized, the focal point is less likely\\* to be cropped out of view**.\n\nFor best results, an aspect-ratio should be similar to the natural image orientation. For example, `5/3` for an image naturally `1024x768` will have better results than for an image `600x1200`.\n\n\\* _Entropy is imperfect and you may not achieve the desired results with every image, particularly with strong light/dark areas_.\n\n## Usage\n\nInstall the plugin:\n\n```bash\nnpm install @11tyrocks/eleventy-plugin-objectfit-focalpoint\n```\n\nThen, include it in your `.eleventy.js` config file:\n\n```js\nconst objectFitFocalPoint = require(\"@11tyrocks/eleventy-plugin-objectfit-focalpoint\");\n\nmodule.exports = (eleventyConfig) =\u003e {\n  eleventyConfig.addPlugin(objectFitFocalPoint);\n};\n```\n\n### Required Image Styles\n\nFor the shortcode to fully work, you will need to include the following styles for the related images. The default class is `image` which can be changed by passing a new string to `imageClasses` within the plugin config.\n\n```css\n.image {\n  /* Required */\n  object-fit: cover;\n\n  /* Recommended but not required */\n  display: block;\n  max-width: 100%;\n\n  /* Optional: Force images to fill their parent container's width */\n  width: 100%;\n}\n```\n\n## Using the Shortcode\n\n**Because the shortcode is async, it is only available for Nunjucks**. If you typically write in Markdown, you can add the following to your frontmatter to be able to use both:\n\n```md\ntemplateEngineOverride: njk, md\n```\n\nTo use the shortcode, pass in an image path and optionally `width` and `height` values, or an aspect `ratio`.\n\n```js\n// Local file - must start with `/`\n{% objectFitFocalPoint image=\"/img/my-image.png\", ratio=\"4/3\" %}\n\n// External file - must begin with http or https\n// ⚠️ Note that the extra processing may slow down your build\n{% objectFitFocalPoint image=\"https://source.unsplash.com/0kCrlrs8gXg/700x900\", width=\"400\", height=\"300\" %}\n```\n\n_Note_: It's recommended to always pass in width and height since [browsers now create space while the image loads](https://www.youtube.com/watch?v=4-d_SoCHeWE) based on the expected aspect-ratio created from those values. This helps alleviate jumping of page content, and improves your [Cumulative Layout Shift Core Web Vitals](https://web.dev/cls/) score.\n\n## Config Options\n\n| Option             | Type   | Default   |\n| ------------------ | ------ | --------- |\n| defaultAspectRatio | string | `'5/3'`   |\n| defaultWidth       | int    | `800`     |\n| defaultHeight      | int    | `480`     |\n| imageClasses       | string | `'image'` |\n| siteInputPath      | string | `'.'`     |\n\nAt minimum, you may need to update the `siteInputPath` if you have customized your input directory within your Eleventy config. This value _should not_ end with `/`.\n\nHere's an example if your input directory is `src`:\n\n```js\neleventyConfig.addPlugin(objectFitFocalPoint, {\n  siteInputPath: \"./src\",\n});\n```\n\n## New to Eleventy?\n\nCheck out my additional resources at [11ty.Rocks](https://11ty.rocks)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5t3ph%2Feleventy-plugin-objectfit-focalpoint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5t3ph%2Feleventy-plugin-objectfit-focalpoint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5t3ph%2Feleventy-plugin-objectfit-focalpoint/lists"}