{"id":16446786,"url":"https://github.com/romainguarinoni/usepositionning","last_synced_at":"2026-05-15T04:32:15.904Z","repository":{"id":48657781,"uuid":"386242433","full_name":"RomainGuarinoni/usepositionning","owner":"RomainGuarinoni","description":"A lightweight library to position elements on the page according to scrolling and available space.","archived":false,"fork":false,"pushed_at":"2021-08-20T13:49:05.000Z","size":926,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-09T11:18:54.296Z","etag":null,"topics":["hooks-library","npm-module","positioning","react"],"latest_commit_sha":null,"homepage":"https://romainguarinoni.github.io/usepositionning/","language":"TypeScript","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/RomainGuarinoni.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}},"created_at":"2021-07-15T09:58:29.000Z","updated_at":"2023-01-23T17:05:33.000Z","dependencies_parsed_at":"2022-09-10T23:31:57.561Z","dependency_job_id":null,"html_url":"https://github.com/RomainGuarinoni/usepositionning","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/RomainGuarinoni%2Fusepositionning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainGuarinoni%2Fusepositionning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainGuarinoni%2Fusepositionning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomainGuarinoni%2Fusepositionning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RomainGuarinoni","download_url":"https://codeload.github.com/RomainGuarinoni/usepositionning/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240842818,"owners_count":19866648,"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":["hooks-library","npm-module","positioning","react"],"created_at":"2024-10-11T09:48:50.223Z","updated_at":"2025-11-21T04:04:29.571Z","avatar_url":"https://github.com/RomainGuarinoni.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# usePositionning\n\n\u003e A lightweight library to position elements on the page according to scrolling and available space.\n\n[![NPM](https://img.shields.io/npm/v/usepositionning.svg)](https://www.npmjs.com/package/usepositionning) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) [![Website shields.io](https://img.shields.io/website-up-down-green-red/http/shields.io.svg)](https://romainguarinoni.github.io/usepositionning/) [![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/RomainGuarinoni/usePositionning/blob/master/LICENSE)\n\n![Peek 17-07-2021 00-57](https://user-images.githubusercontent.com/72984755/126016048-05498cf9-145a-49eb-a56e-75fed22300ff.gif)\n\n## Install\n\n```bash\nnpm install --save usepositionning\n```\n\n```bash\nyarn add --save usepositionning\n```\n\n## What's new ?\n\nusePositionning is a react hook that allows your component (like popUp or select for example) to reposition itself according to the available space on the screen and the position of its parent node when a user scroll or resize the window.\n\n## How does it works ?\n\nusePosition calculates the CSS parameters top / bottom / right / left of a JSX element on every scroll and resize of the window .\nThese properties are calculated according to the position of its parent element, which **must be in relative position**.\n\nHere is how to add usePositionning to your component:\n\n```tsx\nconst [refParent, refChildren, style, position] = usePositionning(\n  {\n    space: 1,\n    preferences: ['bottom-left', 'top-left', 'right-top', 'left-top'],\n    strictMode: false\n  },\n  [open]\n)\n```\n\nusePositionning returns four elements:\n\n- **refParent** is a React.ref that you should pass to the parent element on which your children are positioned :\n\n```tsx\n\u003cdiv className='parent' ref={refParent}\u003e\n  {' '}\n\u003c/div\u003e\n```\n\n-**refChildren** is a React.ref for the pop up element, the one who need to be positionned :\n\n```tsx\n\u003cdiv className='children' ref={refChildren}\u003e\n  {' '}\n\u003c/div\u003e\n```\n\n- **style** are the CSS property that you need to pass to the children JSX.element :\n\n```tsx\n\u003cdiv className='children' style={positions}\u003e\n  {' '}\n\u003c/div\u003e\n```\n\n-**actualPosition** is the actual position of the children element. See below the possible position that it can take\n\n## Parameters of usePositionning\n\n| Name        | Type          | Required | Default | Description                                                                                                                                                          |\n| ----------- | ------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| preferences | Number        | false    | [ ]     | An array of the position order by preference ( see PositionPreference type below                                                                                     |\n| space       | Number        | false    | 0       | The space between the parent and children element                                                                                                                    |\n| strictMode  | Boolean       | false    | false   | If set to `true`, usePositionning will positionned your element only with your preferences, otherwise it will choose the best position in all the position available |\n| deps        | Array od deps | false    | [ ]     | An array of dependencies                                                                                                                                             |\n\nHere are all the position available for the children element :\n\n```tsx\nexport type PositionPreferences =\n  | 'top'\n  | 'bottom'\n  | 'left'\n  | 'right'\n  | 'top-left'\n  | 'top-right'\n  | 'bottom-right'\n  | 'bottom-left'\n  | 'right-top'\n  | 'right-bottom'\n  | 'left-top'\n  | 'left-bottom'\n```\n\n## Example of use\n\n```tsx\nconst Example = (): JSX.Element =\u003e {\n  const [refParent, refChildren, style, actualPositions] = usePositionning({\n    preferences: ['top-left', 'bottom-left'],\n    space: 10\n  })\n\n  return (\n    \u003cdiv className='parentNode' ref={refParent}\u003e\n      \u003cdiv className='childrenNode' ref={refChildren} style={positions}\u003e\n        {' '}\n        \u003cp\u003e {actualPosition} \u003c/p\u003e{' '}\n      \u003c/div\u003e\n      \u003cstyle jsx\u003e\n        {`\n          .parentNode {\n            position: relative;\n            width: 200px;\n            height: 300px;\n          }\n\n          .childrenNode {\n            width: 500px;\n            height: 200px;\n          }\n        `}\n      \u003c/style\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\nMIT © [RomainGuarinoni](https://github.com/RomainGuarinoni)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromainguarinoni%2Fusepositionning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromainguarinoni%2Fusepositionning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromainguarinoni%2Fusepositionning/lists"}