{"id":24656944,"url":"https://github.com/rob2d/use-viewport-sizes","last_synced_at":"2025-04-09T07:08:05.265Z","repository":{"id":34739472,"uuid":"182201601","full_name":"rob2d/use-viewport-sizes","owner":"rob2d","description":"tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce for updates for optimal rendering.","archived":false,"fork":false,"pushed_at":"2025-03-30T20:23:57.000Z","size":8471,"stargazers_count":40,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-30T20:28:21.513Z","etag":null,"topics":["dimensions","hooks","nextjs","npm-package","react","react-hooks","react-ssr","reactjs","resize","sizes","viewport","window"],"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/rob2d.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":"2019-04-19T04:30:05.000Z","updated_at":"2025-03-30T20:21:41.000Z","dependencies_parsed_at":"2024-06-21T14:27:39.494Z","dependency_job_id":"f42eec54-f568-434e-aed6-c5ab4a04a830","html_url":"https://github.com/rob2d/use-viewport-sizes","commit_stats":{"total_commits":34,"total_committers":2,"mean_commits":17.0,"dds":"0.11764705882352944","last_synced_commit":"7aec509b50a012110e51e4a6815dfe98e2d53c79"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob2d%2Fuse-viewport-sizes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob2d%2Fuse-viewport-sizes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob2d%2Fuse-viewport-sizes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob2d%2Fuse-viewport-sizes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rob2d","download_url":"https://codeload.github.com/rob2d/use-viewport-sizes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994121,"owners_count":21030050,"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":["dimensions","hooks","nextjs","npm-package","react","react-hooks","react-ssr","reactjs","resize","sizes","viewport","window"],"created_at":"2025-01-25T23:57:18.799Z","updated_at":"2025-04-09T07:08:05.237Z","avatar_url":"https://github.com/rob2d.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# use-viewport-sizes #\r\n\r\n[![npm](https://img.shields.io/npm/v/use-viewport-sizes.svg?color=blue)](https://www.npmjs.com/package/use-viewport-sizes) [![npm](https://img.shields.io/npm/dw/use-viewport-sizes.svg?color=red)]() [![GitHub issues](https://img.shields.io/github/issues-raw/rob2d/use-viewport-sizes.svg)](https://github.com/rob2d/use-viewport-sizes/issues) \r\n![Github Workflow Status](https://github.com/rob2d/use-viewport-sizes/actions/workflows/node.js.yml/badge.svg)\r\n[![NPM](https://img.shields.io/npm/l/use-viewport-sizes.svg)](https://github.com/rob2d/use-viewport-sizes/blob/master/LICENSE)\r\n\r\nA lightweight, TypeScript-compatible React hook for tracking viewport sizes in your components. Includes optional debounce, throttle, and custom memoization for optimized rendering.\r\n\r\n## Table of Contents\r\n- [Installation](#installation)\r\n- [Benefits](#benefits)\r\n- [Usage](#usage)\r\n  - [Basic Use-case](#basic-use-case)\r\n  - [Measure/Update only on one dimension](#measureupdate-only-on-one-dimension)\r\n  - [With Throttling](#with-throttling)\r\n  - [With Debouncing](#with-debouncing)\r\n  - [Only update vpW/vpH passed on specific conditions](#only-update-vpwvph-passed-on-specific-conditions)\r\n- [Support](#support)\r\n- [License](#license)\r\n\r\n## Installation ##\r\n\r\n```\r\nnpm install -D use-viewport-sizes\r\n```\r\n\r\n## Benefits ##\r\n- extremely lightweight and zero dependencies -- adds **2.38kb** pre gzip, and **1.09kb** after gzip.\r\n- only one `window.onresize` handler used to subscribe to any changes in an unlimited number of components no matter the use-cases.\r\n- optional debounce to delay updates until user stops dragging their window for a moment; this can make expensive components with size-dependent calculations run much faster and your app feel smoother.\r\n- debouncing does not create new handlers or waste re-renders in your component; the results are also pooled from only one resize result.\r\n- optional hash function to update component subtree only at points you would like to.\r\n- supports lazy loaded components and SSR out of the box.\r\n- compatible with React v16 | v17 | v18 | v19\r\n\r\n\r\n## Usage ##\r\n\r\n### **See it in Action** ###\r\n\r\n\u003ccenter\u003e\r\n\u003cimg src=\"./doc/use-viewport-sizes.gif\" /\u003e\r\n\r\n[CodeSandbox IDE](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-i8urr)\r\n\r\n\u003c/center\u003e\r\n\r\n### **Basic Use-case**\r\n*registers dimension changes on every resize event immediately*\r\n\r\n```js\r\nimport useViewportSizes from 'use-viewport-sizes'\r\n\r\nfunction MyComponent(props) {\r\n  const [vpWidth, vpHeight] = useViewportSizes();\r\n\r\n  // ...renderLogic\r\n}\r\n```\r\n\r\n### **Measure/Update only on one dimension**\r\n\r\nIf passed `options.dimension` as `w` or `h`, only the viewport width or height will be\r\nmeasured and observed for updates.\r\nThe only dimension returned in the return array value will be the width or height, according\r\nto what was passed.\r\n\r\n```js\r\nimport useViewportSizes from 'use-viewport-sizes';\r\n\r\nfunction MyComponent(props) {\r\n  const [vpHeight] = useViewportSizes({ dimension: 'h' });\r\n\r\n  // ...renderLogic\r\n}\r\n```\r\n\r\n### **With Throttling**\r\n\r\nIf passed `options.throttleTimeout`, or options are entered as a `Number`, dimension changes\r\nare registered on a throttled basis e.g. with a maximum frequency.\r\n\r\nThis is useful for listening to expensive components such as data grids which may be too\r\nexpensive to re-render during window resize dragging.\r\n\r\n```js\r\nimport useViewportSizes from 'use-viewport-sizes';\r\n\r\nfunction MyExpensivelyRenderedComponent(props) {\r\n  // throttled by 1s between updates\r\n  const [vpWidth, vpHeight] = useViewportSizes({ throttleTimeout: 1000 }); \r\n\r\n  // ...renderLogic\r\n}\r\n```\r\n\r\n### **With Debouncing**\r\n\r\nIf passed `options.debounceTimeout`, dimension changes are registered only when a user stops dragging/resizing the window for a specified number of miliseconds. This is an alternative behavior to `throttleTimeout` where it may be less\r\nimportant to update viewport the entire way that a user is resizing.\r\n\r\n```js\r\nimport useViewportSizes from 'use-viewport-sizes';\r\n\r\nfunction MyExpensivelyRenderedComponent(props) {\r\n  // debounced by 1s between updates\r\n  const [vpWidth, vpHeight] = useViewportSizes({ debounceTimeout: 1000 });\r\n\r\n  // ...renderLogic\r\n}\r\n```\r\n\r\n### **Only update vpW/vpH passed on specific conditions**\r\nIf passed an `options.hasher` function, this will be used to calculate a hash that only updates the viewport when the calculation changes. In the example here, we are using it to detect when we have a breakpoint change which may change how a component is rendered if this is not fully possible or inconvenient via CSS `@media` queries. The hash will also be available as the 3rd value returned from the hook for convenience.\r\n\r\n```js\r\nimport useViewportSizes from 'use-viewport-sizes';\r\n\r\nfunction getBreakpointHash({ vpW, vpH }) {\r\n  if(vpW \u003c= 240) { return 'xs' }\r\n  if(vpW \u003c= 320) { return 'sm' }\r\n  else if(vpW \u003c= 640) { return 'md' }\r\n  return 'lg';\r\n}\r\n\r\nfunction MyBreakpointBehaviorComponent() {\r\n  const [vpW, vpH] = useViewportSizes({ hasher: getBreakpointHash });\r\n\r\n  // do-something in render and add new update for vpW, \r\n  // vpH in this component's subtree only when a breakpoint\r\n  // hash updates\r\n}\r\n```\r\n\r\n## Support\r\nIf you find any issues or would like to request something changed, please feel free to [post an issue on Github](https://github.com/rob2d/use-viewport-sizes/issues/new).\r\n\r\nOtherwise, if this was useful and you'd like to show your support, no donations necessary, but please consider [checking out the repo](https://github.com/rob2d/use-viewport-sizes) and giving it a star (⭐).\r\n\r\n## License ##\r\n\r\nOpen Source **[MIT license](http://opensource.org/licenses/mit-license.php)**\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frob2d%2Fuse-viewport-sizes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frob2d%2Fuse-viewport-sizes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frob2d%2Fuse-viewport-sizes/lists"}