{"id":13397280,"url":"https://github.com/sgomes/css-aspect-ratio","last_synced_at":"2025-03-13T23:32:16.198Z","repository":{"id":72275160,"uuid":"83463488","full_name":"sgomes/css-aspect-ratio","owner":"sgomes","description":"A tiny module to help preserve aspect ratio in pure CSS","archived":false,"fork":false,"pushed_at":"2017-06-02T13:03:02.000Z","size":14,"stargazers_count":109,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-09-20T08:34:38.187Z","etag":null,"topics":["aspect-ratio","css"],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgomes.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}},"created_at":"2017-02-28T18:01:21.000Z","updated_at":"2023-08-08T21:37:20.000Z","dependencies_parsed_at":"2024-01-18T10:16:57.150Z","dependency_job_id":"cb0c2eb7-fe11-4a94-be03-fbf63367e233","html_url":"https://github.com/sgomes/css-aspect-ratio","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"ec9572877fa360e61bd9dd10fd4c09653949a7fa"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgomes%2Fcss-aspect-ratio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgomes%2Fcss-aspect-ratio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgomes%2Fcss-aspect-ratio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgomes%2Fcss-aspect-ratio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgomes","download_url":"https://codeload.github.com/sgomes/css-aspect-ratio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243500253,"owners_count":20300761,"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":["aspect-ratio","css"],"created_at":"2024-07-30T18:01:14.911Z","updated_at":"2025-03-13T23:32:15.884Z","avatar_url":"https://github.com/sgomes.png","language":"CSS","funding_links":[],"categories":["CSS"],"sub_categories":[],"readme":"# CSS Aspect Ratio\n\nThis package provides a simple implementation of fixed aspect ratio in pure CSS.\nIt requires support for [CSS Custom Properties](https://www.w3.org/TR/css-variables-1/).\n\nModular implementation approach adapted from\nhttps://sgom.es/posts/2017-02-17-css-custom-properties-as-your-api/\n\nCSS-only aspect ratio trick adapted from\nhttps://alistapart.com/article/creating-intrinsic-ratios-for-video\n\n\n## Rationale / background\n\nA common problem is how to avoid content shifting down as images load. This is usually solved by\nadding the height and width of an image in HTML, so that the browser can allocate enough space\nfor the content ahead of time.\n\n```html\n\u003cimg src=\"kitten.jpg\" height=\"1024\" width=\"768\" alt=\"A cute kitten\"\u003e\n```\n\nHowever, if you want to adjust the dimensions for the image in CSS (say, by applying a `max-width`\nto the image), you lose the ability to maintain the aspect ratio. Instead, the width and height\nget applied separately, and the image gets deformed.\n\nThis package allows you to specify the width and have the height calculated automatically,\nensuring that the aspect ratio is maintained even if the image is resized.\n\nIt's also generic enough to be applied to any block, not just images.\n\n\n## Install\n\n```sh\nnpm i --save-dev css-aspect-ratio\n```\n\n\n## Import\n\n### Sass\n\nIn Sass, first make sure `node_modules` is in your `includePaths`. Then:\n\n```scss\n@import \"css-aspect-ratio/css-aspect-ratio\";\n```\n\n### Less\n\nIn Less, install `less-plugin-npm-import` and do:\n\n```less\n@import (inline) \"npm://css-aspect-ratio/css-aspect-ratio.css\";\n```\n\n### Plain CSS\n\nIn plain CSS, make sure you use a bundler or build tool to copy dependencies. To import:\n\n`@import /path/to/css-aspect-ratio.css;`\n\nYou can also use unpkg as a CDN:\n\n```css\n@import https://unpkg.com/css-aspect-ratio@1/css-aspect-ratio.css;\n```\n\n\n## Usage\n\nIn HTML:\n\n```html\n\u003cdiv class=\"aspect-ratio\"\n style=\"width: 768px; --aspect-ratio-w: 4; --aspect-ratio-h: 3;\"\u003e\n\n  \u003cimg src=\"kitten.jpg\" alt=\"A cute kitten\"\u003e\n\u003c/div\u003e\n```\n\n`aspect-ratio` takes two custom properties:\n- `--aspect-ratio-w` defines the width portion of the aspect ratio, e.g. 16 in 16:9.\n- `--aspect-ratio-h` defines the height portion of the aspect ratio, e.g. 9 in 16:9.\n\n\n## Progressive enhancement\n\nCSS Aspect Ratio works as progressive enhancement, leaving the resizing entirely to the browser\nif custom properties are not supported. This means that for things like images, aspect ratio will\nbe preserved, but vertical space will not be allocated ahead of time, resulting in content\nshifting down during load.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgomes%2Fcss-aspect-ratio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgomes%2Fcss-aspect-ratio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgomes%2Fcss-aspect-ratio/lists"}