@leafygreen-ui/hooks
Version:
LeafyGreen UI Kit Custom Hooks
221 lines (149 loc) • 9.17 kB
Markdown
# Hooks
## Installation
### Yarn
```shell
yarn add @leafygreen-ui/hooks
```
### NPM
```shell
npm install @leafygreen-ui/hooks
```
## useEventListener
Hook to create and remove eventListeners
### Example
```js
import { useEventListener } from '@leafygreen-ui/hooks';
useEventListener('click', handleClick, { enabled });
```
### Properties
| Prop | Type | Description | Default |
| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `type` | `Global Event Handler`, `string` | Type of event to listen for. | |
| `eventCallback` | `function` | Callback executed when event is triggered. | |
| `optional` | `object` | Optional third argument passed to function with implementation specifications. | |
| `optional.options` | `AddEventListenerOptions` excluding `once` | Parameter to specify options passed to the eventListener. To enable the `once` option, see `optional.enabled`. | |
| `optional.enabled` | `boolean`, `'once'` | Determines whether the event handler is attached or not. Setting this to `"once"` will ensure the event handler will be detached after the initial time an event is triggered. | `true` |
| `optional.dependencies` | `Array` | Array to be passed to useEffect hook, such that the hook will only run if the array's values have changed. | `[enabled, type]` |
| `optional.element` | `Document`, `HTMLElement` | The DOM node to attach the event handler to. Defaults to `document`. | `document` |
## useEscapeKey
Hook that listens for `EscapeKey` press.
### Example
```js
import { useEscapeKey } from '@leafygreen-ui/hooks';
useEscapeKey(handleEscapeCallback);
```
### Properties
| Prop | Type | Description | Default |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function` | Callback executed when `EscapeKey` is pressed. | |
| `optional` | `object` | Optional argument passed to function with implementation specifications. See supported parameters for useEventHandler. | |
## useMutationObserver
### Example
```js
import { useMutationObserver } from '@leafygreen-ui/hooks';
const lastTimeContentElMutated = useMutationObserver(
target,
mutationOptions,
() => Date.now(),
adjustOnMutation,
);
```
### Properties
| Prop | Type | Description | Default |
| ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `target` | `HTMLElement`, `null` | `HTMLElement` to subscribe to changes to. | |
| `options` | `MutationObserverInit` | Object with information about what DOM changes to subscribe to. [Docs here](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserverInit) | |
| `callback` | `function` | Callback function to execute inside of MutationObserver instance. | |
| `enabled` | `boolean` | Determines whether the event handler is attached or not. | `true` |
## useViewportSize
Hook to subscribe to changes in viewport size
### Example
```js
const viewportSize = useViewportSize();
```
## usePoller
Hook to create a Poller that polls at a given interval.
If your `onPoll` handler returns a `Promise` it will wait for the Promise to resolve or reject before scheduling the next interval.
This hooks also makes use of the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API). If the page is `hidden` then polling will stop. When a page becomes `visible` again then polling will resume.
### Example
```js
import { usePoller } from '@leafygreen-ui/hooks';
usePoller(onPoll, {
interval: 30000,
immediate: true,
enabled: true,
});
```
### Properties
| Prop | Type | Description | Default |
| -------------------- | ---------- | -------------------------------------------------------------------- | ------- |
| `onPoll` | `function` | Callback executed when poll interval occurs. | |
| `optional.interval` | `number` | What interval the onPoll should be called. | `30000` |
| `optional.immediate` | `boolean` | If we immediately poll, if false we wait till first interval occurs. | `true` |
| `optional.enabled` | `boolean` | Is polling enabled. | `true` |
# usePrevious
Hook to retrieve a value from the previous render.
### Example
```js
import { usePrevious } from '@leafygreen-ui/hooks';
const Example = ({nextValue: number}) => {
const value = usePrevious(nextValue);
return <div>{value}</div>;
}
// First render
<Example nextValue={42} /> // will render an empty `div`
// Second render
<Example nextValue={2020} /> // will render "42"
// Third render
<Example nextValue={0} /> // will render "2020"
```
# useIsomorphicLayoutEffect
Drop-in replacement for `useLayoutEffect` that does not produce warnings during server-side rendering. If your project uses the `react-hooks/exhaustive-deps` ESLint rule, it's recommended to add `useIsomorphicLayoutEffect` to the `additionalHooks` of the rule. Example:
```js
rules: {
'react-hooks/exhaustive-deps': [
'warn',
{
additionalHooks: '(useIsomorphicLayoutEffect)'
}
]
}
```
# useIdAllocator
Generates an SSR-compatible unique id based on a prefix string and an optional idProp parameter.
### Example
```js
import { useIdAllocator } from '@leafygreen-ui/hooks';
useIdAllocator({ prefix: 'select-component', id: idProp });
```
## useForwardedRef
Returns a MutableRefObject from the forwarded ref.
### Example
```jsx
import { useForwardedRef } from '@leafygreen-ui/hooks';
const MyComponent = React.forwardRef((props, forwardedRef) => {
const ref = useForwawrdedRef(forwardedRef, null);
});
```
### Properties
| Prop | Type | Description | Default |
| -------------------- | ------------------------------------------- | ------------------------ | ------- |
| `forwardedRefOrRefs` | `SettableRef`, `Array<SettableRef>`, `null` | The forwarded ref | |
| `initialValue` | `T` | Initial value of the ref | |
## useDynamicRefs
useDynamicRefs is a hook that allows you to create multiple refs for dynamically created elements. Use the `prefix` property to create multiple sets of dynamic refs.
### Example
```jsx
import { useDynamicRefs } from '@leafygreen-ui/hooks';
const getRef = useDynamicRefs();
...
return ['a','b','c'].map(x => {
const divRef = getRef(x)
return <div ref={divRef}>{x}</div>
})
```
### Properties
| Prop | Type | Description | Default |
| -------- | -------- | --------------------------------------------------- | ------- |
| `prefix` | `string` | Optional prefix to that genterates a ref name space | |