https://github.com/romainguarinoni/usepositionning
A lightweight library to position elements on the page according to scrolling and available space.
https://github.com/romainguarinoni/usepositionning
hooks-library npm-module positioning react
Last synced: about 1 month ago
JSON representation
A lightweight library to position elements on the page according to scrolling and available space.
- Host: GitHub
- URL: https://github.com/romainguarinoni/usepositionning
- Owner: RomainGuarinoni
- License: mit
- Created: 2021-07-15T09:58:29.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-20T13:49:05.000Z (almost 5 years ago)
- Last Synced: 2025-02-09T11:18:54.296Z (over 1 year ago)
- Topics: hooks-library, npm-module, positioning, react
- Language: TypeScript
- Homepage: https://romainguarinoni.github.io/usepositionning/
- Size: 904 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# usePositionning
> A lightweight library to position elements on the page according to scrolling and available space.
[](https://www.npmjs.com/package/usepositionning) [](https://standardjs.com) [](https://romainguarinoni.github.io/usepositionning/) [](https://github.com/RomainGuarinoni/usePositionning/blob/master/LICENSE)
## Install
```bash
npm install --save usepositionning
```
```bash
yarn add --save usepositionning
```
## What's new ?
usePositionning 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.
## How does it works ?
usePosition calculates the CSS parameters top / bottom / right / left of a JSX element on every scroll and resize of the window .
These properties are calculated according to the position of its parent element, which **must be in relative position**.
Here is how to add usePositionning to your component:
```tsx
const [refParent, refChildren, style, position] = usePositionning(
{
space: 1,
preferences: ['bottom-left', 'top-left', 'right-top', 'left-top'],
strictMode: false
},
[open]
)
```
usePositionning returns four elements:
- **refParent** is a React.ref that you should pass to the parent element on which your children are positioned :
```tsx
{' '}
```
-**refChildren** is a React.ref for the pop up element, the one who need to be positionned :
```tsx
{' '}
```
- **style** are the CSS property that you need to pass to the children JSX.element :
```tsx
{' '}
```
-**actualPosition** is the actual position of the children element. See below the possible position that it can take
## Parameters of usePositionning
| Name | Type | Required | Default | Description |
| ----------- | ------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| preferences | Number | false | [ ] | An array of the position order by preference ( see PositionPreference type below |
| space | Number | false | 0 | The space between the parent and children element |
| 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 |
| deps | Array od deps | false | [ ] | An array of dependencies |
Here are all the position available for the children element :
```tsx
export type PositionPreferences =
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'top-left'
| 'top-right'
| 'bottom-right'
| 'bottom-left'
| 'right-top'
| 'right-bottom'
| 'left-top'
| 'left-bottom'
```
## Example of use
```tsx
const Example = (): JSX.Element => {
const [refParent, refChildren, style, actualPositions] = usePositionning({
preferences: ['top-left', 'bottom-left'],
space: 10
})
return (
{' '}
{actualPosition}
{' '}
{`
.parentNode {
position: relative;
width: 200px;
height: 300px;
}
.childrenNode {
width: 500px;
height: 200px;
}
`}
)
}
```
MIT © [RomainGuarinoni](https://github.com/RomainGuarinoni)