https://github.com/everweij/solid-boundaries
Utility to track the boundaries of html-elements in SolidJS
https://github.com/everweij/solid-boundaries
bounds measure position resize size solidjs
Last synced: about 1 year ago
JSON representation
Utility to track the boundaries of html-elements in SolidJS
- Host: GitHub
- URL: https://github.com/everweij/solid-boundaries
- Owner: everweij
- License: mit
- Created: 2022-04-01T22:02:49.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2022-05-04T09:53:37.000Z (about 4 years ago)
- Last Synced: 2025-05-15T03:50:06.137Z (about 1 year ago)
- Topics: bounds, measure, position, resize, size, solidjs
- Language: TypeScript
- Homepage:
- Size: 96.7 KB
- Stars: 18
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.MD
- License: LICENSE
Awesome Lists containing this project
README
solid-boundaries
Helps you to track the size and position of html-elements in solid-js.
## What does it do?
See it in action [here](https://7j26ix.sse.codesandbox.io/), or see it on [CodeSandbox](https://codesandbox.io/s/solid-boundaries-example-7j26ix?file=/src/main.tsx)!
This small library exposes a small reactive primitive which tracks the **size** and **position** (_bounds_) of a specific html-element (subject). _Bounds_, just like when you call `.getBoundingClientRect()`, have the following structure:
```ts
interface Bounds {
top: number;
left: number;
right: number;
bottom: number;
width: number;
height: number;
}
```
This is useful for all kinds of things, like building tooltips, popovers, or other behavior and interactions related to changes regarding size and positions.
Bounds update in response to:
- scrolling - the entire window as well as (nested-)scroll-containers
- resizing - the entire window as well as the subject
- mutations in the document - to be more specific:
- any changes that may affect styling (style/class attributes)
- adding or removal of other html-elements
## Install
```bash
npm install solid-boundaries
```
## Usage
```tsx
import { trackBounds } from "solid-boundaries";
function App() {
const { ref, bounds } = trackBounds();
// Make sure to pass the ref properly to the element you
// want to track, and do something with fun with the bounds!
// Note: the bounds are `null` when the element has not been
// connected to the DOM yet.
return (
{bounds() && JSON.stringify(bounds())}
)
}
```
## API
```tsx
interface Bounds {
top: number;
left: number;
right: number;
bottom: number;
width: number;
height: number;
}
interface Config {
/**
* Whether to actively track the element's position.
* @default () => true
*/
enabled?: Accessor;
/**
* Whether to actively track mutations in the DOM.
* @default () => true
*/
trackMutations?: boolean;
/**
* Whether to actively track resizes of the element you're
* tracking or of the entire window.
* @default () => true
*/
trackResize?: boolean;
/**
* Whether to actively track scrolling.
* @default () => true
*/
trackScroll?: boolean;
/**
* Defines specific keys of the boundary to track.
* By default all keys are tracked.
* @default ["top", "right", "bottom", "left", "width", "height"]
*/
keys?: BoundsKeys;
/**
* Whether not to show warning messages in the console
*/
suppressWarnings?: boolean;
}
type TrackBoundsProps = {
/**
* Setter which should be passed to the `ref` prop of the
* element you want to track.
*/
ref: Setter;
/**
* The bounds of the element you are tracking.
* Note: returns `null` if the element is not connected
* to the DOM.
*/
bounds: Accessor;
/**
* Provides a reference to the element.
*/
element: Accessor;
};
function trackBounds(config?: Config): TrackBoundsProps;
```
## Browser compatibility
This library makes use of `ResizeObserver` and `MutationObserver`. If you need to support older browsers I recommend to use a polyfill, otherwise certain behavior will be skipped.
## Contributing
Want to contribute to solid-boundaries? Your help is very much appreciated!
Please consult the [contribution guide](./CONTRIBUTING.MD) on how to get started.
## License
MIT © [everweij](https://github.com/everweij)