{"id":17470805,"url":"https://github.com/micropackage/vw","last_synced_at":"2025-04-21T16:37:15.118Z","repository":{"id":40854785,"uuid":"241064693","full_name":"micropackage/vw","owner":"micropackage","description":"Better vw and vh units which takes into account the scrollbars","archived":false,"fork":false,"pushed_at":"2023-01-07T04:32:58.000Z","size":1736,"stargazers_count":7,"open_issues_count":12,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-19T05:17:21.425Z","etag":null,"topics":["bracketspace","micropackage","mixins","sass","scrollbar","scrollbar-width","viewport-units","viewport-width"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micropackage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-17T09:15:28.000Z","updated_at":"2025-02-05T19:42:09.000Z","dependencies_parsed_at":"2023-02-06T11:45:17.937Z","dependency_job_id":null,"html_url":"https://github.com/micropackage/vw","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fvw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fvw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fvw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropackage%2Fvw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micropackage","download_url":"https://codeload.github.com/micropackage/vw/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249834788,"owners_count":21331988,"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":["bracketspace","micropackage","mixins","sass","scrollbar","scrollbar-width","viewport-units","viewport-width"],"created_at":"2024-10-18T16:10:25.951Z","updated_at":"2025-04-20T01:01:50.510Z","avatar_url":"https://github.com/micropackage.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Viewport Width\n\n[![BracketSpace Micropackage](https://img.shields.io/badge/BracketSpace-Micropackage-brightgreen)](https://bracketspace.com)\n[![npm](https://img.shields.io/npm/v/@micropackage/vw)](https://www.npmjs.com/package/@micropackage/vw)\n[![License](https://img.shields.io/npm/l/@micropackage/vw)](https://www.npmjs.com/package/@micropackage/vw)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://bracketspace.com/extras/micropackage/micropackage-small.png\" alt=\"Micropackage logo\"/\u003e\n\u003c/p\u003e\n\n## 🧬 About Viewport Width\n\n_**Note:** Despite the name this package works with both viewport **width** and **height** units_\n\nThis package is meant to solve the common problem with viewport units in CSS. These are simply speaking percent units which always remain relative to viewport.\n```css\n.wrap {\n\twidth: 800px;\n\tposition: relative;\n}\n\n.wrap img {\n\twidth: 100%;\n}\n\n.wrap .alignfull {\n\twidth: 100vw;\n\tposition: relative;\n\tleft: 50%;\n\ttransform: translateX(-50%);\n}\n```\nIn the example above `img` will have 100% of the parent width, which is `800px` while any element with class `alignfull` will have the 100% of a viewport. This is a simple solution for making full width section inside a narrower container: the element is positioned relatively which allows us to move it to the center of parent div by setting `left: 50%` and then move it back to the edge of the screen with `transform` property (where percentage values are relative to the element itself, not the parent).\n\n### The Problem\nThere is one problem: viewport dimmensions include potential scrollbars. So on a typical website with vertical scrollbar any `.alignfull` element from the example will be wider than the actual body width. This could be easily corrected using `calc` function. Scrollbar width is in most cases 17px wide.\n```css\n.wrap .alignfull {\n\twidth: calc(100vw - 17px);\n\t...\n}\n```\nBut...\n\nIn mobile browsers scrollbar does not count into viewport (it usually only appears as a narrow scrolling indicator while user drags the page around). We could write some media queries for it and use `calc` only in desktop browser. But it won't be easy, it won't be enought to check the viewport size, we should use some JS to determine whether current browser has permanently visible scrollbar or not.\n\nAlso we can't be sure if the scrollbar is 17px wide since this value is not standarized. Most desktop browsers use this size, but some of them have templating mechanisms which allow the templates to modifu UI elements. Firefox has an option to use narrow scrollbars...\n\n### The Solution\nThat's why this package was created. it contains very simple JS code and a bunch of [Sass](https://sass-lang.com/) mixins to work with viewport units in a more convenient way.\nUsing this package you just use the mixin:\n```scss\n.element {\n\twidth: vw(100);\n}\n```\ninstead of\n```css\n.element {\n\twidth: 100vw;\n}\n```\nSee [Usage](#-usage) section for more information.\n\n## 💾 Installation\n\n``` bash\nnpm install @micropackage/vw\n```\nor\n``` bash\nyarn add @micropackage/vw\n```\n\n## 🕹 Usag\nThis package contains few [Sass](https://sass-lang.com/) mixins and is intended to be used with [Sass](https://sass-lang.com/). Hovewer the script might be useful also in plain CSS or with any other CSS extension language.\n\n### The Script\nBefore you start you need to add the script to your site. You can just include the script directly in your HTML:\n```html\n\u003cscript src=\"/node_modules/@micropackage/vw/dist/vw.js\"\u003e\u003c/script\u003e\n```\nor import the package:\n```javascript\nimport '@micropackage/vw';\n```\nWhat the script does is it recognizes if the browser contains the scrollbar and stores the scrollbar width in a css variable. The value is accessible in plain css using `var` function:\n```css\n.element {\n\twidth: calc(100vw - var(--scrollbar-width));\n}\n```\nThe value is updated on resize event, and is set to 0 if there is no scrollbar.\n\nIf you would like to use just the script, this is it.\n\n### The Mixins\n\nWhile you have the script imported you will also need to import sass mixins:\n```scss\n@import \"@micropackage/vw/src/scss/mixins\";\n```\nDepending on the build tool you might need to use some special config to import SCSS files from `node_modules`.\n\n#### `vw()`\nThis mixin is a replacement for the default `vw` unit.\n\n*Example:*\n```scss\n.element {\n\twidth: vw(47); // This is replacement for \"width: 47vw\";\n}\n```\n*Generated CSS:*\n```scss\n.element {\n\twidth: calc(0.47 * (100vw - var(--scrollbar-width))); // This is replacement for \"width: 47vw\";\n}\n```\n\nFine, but let's suppose we need to use the viewport-relative value in a more complex `calc` call. What then?\n\n#### `vw-raw()`\nThis mixin will generate the calculation formula without the `calc()` wrapped arround, so it can be used in custom `calc()` call.\n\n*Example:*\n```scss\n.element {\n\twidth: vw(50);\n\tmargin-left: calc(50% - #{ vw-raw(50) });\n}\n```\n*Generated CSS:*\n```scss\n.element {\n\twidth: 0.5 * (100vw - var(--scrollbar-width));\n\tmargin-left: calc(50% - 0.5 * (100vw - var(--scrollbar-width)));\n}\n```\nIf the `.element` would be placed inside some centrally positioned container it would stretch to the left side of the screen while it's right edge would be aligned to the center of the screen. It's actually useful, trust me :)\n\n#### `vh()` and `vh-raw()`\nIn most cases horizontal scrollbar is not desired on a website. It might be useful in a web app UI, but usually will be added to a specific elements, not entire document. But someone might need it so...\n\nThis two mixins are the same as the first two, but they use `vh` unit instead of `vw`.\n\n*Example:*\n```scss\n.element {\n\tposition: absolute;\n\twidth: 100%;\n\ttop: vh(50);\n\theight: calc(#{ vh-raw(50) } - 40px);\n}\n```\n\n## 📦 About the Micropackage project\n\nMicropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.\n\nThe aim is to have multiple packages which can be put together to create something bigger by defining only the structure.\n\nMicropackages are maintained by [BracketSpace](https://bracketspace.com).\n\n## 📖 Changelog\n\n[See the changelog file](./CHANGELOG.md).\n\n## 📃 License\n\nGNU General Public License (GPL) v3.0. See the [LICENSE](./LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropackage%2Fvw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicropackage%2Fvw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropackage%2Fvw/lists"}