npm package: @highlight-ui/utils-hooks
Description: A collections of React hooks that are used by UI-components in Personio
Author: Personio GmbH & Co. KG
Latest version: 3.5.1

# `@highlight-ui/utils-hooks`

## Installation

```
yarn add @highlight-ui/utils-hooks
```

## Hooks

- [useAutoPositioner](#useautopositioner)
- [useAutoPosition](#useautoposition)
- [useForkRef](#useforkref)
- [useClickOutside](#useclickoutside)
- [useScrollObserver](#usescrollobserver)

---

## useAutoPositioner

_This component is deprecated_

A wrapper for the [usePopper](https://popper.js.org/react-popper/v2/hook/) from
the [react-popper](https://github.com/popperjs/react-popper) library.

### Usage

Accepts a Popper.js `options` object as an argument and returns the `styles` and
`attributes` values from the `usePopper` hook. For convenience, the hook also
returns `setReferenceElement` and `setPopperElement` functions.

```jsx
import { useAutoPositioner } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const { setReferenceElement, setPopperElement, styles, attributes } =
    useAutoPositioner();

  return (
    <div ref={setReferenceElement}>
      <div
        ref={setPopperElement}
        style={{ ...styles.popper }}
        {...attributes.popper}
      ></div>
    </div>
  );
};
```

## useAutoPosition

Calculating position of "floating" elements like tooltips, popovers, dropdowns,
menus, and more.

### Usage

Accepts a config as an argument and returns the `styles`, `triggerRef` and
`floatRef` functions.

```ts
type Options = {
  // Position of the element to the trigger element. Default: bottom-start
  placement: Placement;
  // Automatic position based on the space around the trigger. This overrides flip and placement options. Default: Disabled
  auto: AutoConfig | null | false;
  // Flip position if there is not enough space on the placement area: Default: Enabled
  flip: FlipConfig | null | false;
  // Offset from the trigger element: Default: Enabled
  offset: OffsetConfig | null | false;
};
```

```jsx
import { useAutoPosition } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const { triggerRef, floatRef, styles } = useAutoPosition();

  return (
    <>
      <div ref={triggerRef}>Trigger</div>
      <div ref={floatRef} style={{ ...styles }}>
        Floating tooltip
      </div>
    </>
  );
};
```

## useAutoIntegration

Wrap above useAutoPosition with interaction controls. Based on the config
updated open property

### Usage

Accepts a config as an argument and returns the `styles`, `open`,
`getTriggerProps`, `getFloatProps`, `triggerRef` and `floatRef` functions.

```ts
type Options = AutoPositionOptions & {
  // Auto open on hover. Default: Enabled
  hover?: HoverConfig;
  // Auto open on click.  Default: Disabled
  click?: EnableConfig;
  // Auto open on focus.  Default: Enabled
  focus?: EnableConfig;
  // Set role to automatically add a11y params to floater. Default: Disabled
  role?: RoleConfig;
  // Auto close.  Default: Enabled
  dimish?: EnableConfig;
};
```

```jsx
import { useAutoInteractions } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const { triggerRef, floatRef, styles, open, getTriggerProps, getFloatProps } =
    useAutoInteractions();

  return (
    <>
      <div
        ref={triggerRef}
        // Functions like onClick, onHover, ... are at risk of being overriden
        // to prevent that we add then into the getTriggerProps that will join
        // the props/callbacks if it needs/uses it
        {...getTriggerProps({
          onClick: () => {
            console.log('clicked');
          },
        })}
      >
        Trigger
      </div>
      {open && (
        <div
          ref={floatRef}
          style={{ ...styles }}
          // Functions like onClick, onHover, ... are at risk of being overriden
          // to prevent that we add then into the getTriggerProps that will join
          // the props/callbacks if it needs/uses it
          {...getFloatProps({
            onClick: () => {
              console.log('clicked');
            },
          })}
        >
          Floating tooltip
        </div>
      )}
    </>
  );
};
```

## useForkRef

Allows multiple ref objects/callbacks to be combined so that they can be passed
as a single callback ref.

### Usage

```jsx
import React from 'react';
import { useForkRef } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const firstRef = React.useRef();
  const secondRef = React.useRef();
  const finalRef = React.useRef([firstRef, secondRef]);

  return <div ref={finalRef}></div>;
};
```

## useClickOutside

Allows attaching a click-outside listener to a target element.

### Usage

```jsx
import { useClickOutside } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const onClickOutside = () => {
    console.log('clicked outside');
  };
  const setElement = useClickOutside(onClickOutside);

  return (
    <div>
      <span>Outer Div</span>
      <div ref={setElement}>
        <span>Inner Div</span>
      </div>
    </div>
  );
};
```

## useScrollObserver

Allows attaching a scroll listener to a target element.

### Usage

```jsx
import { useScrollObserver } from '@highlight-ui/utils-hooks';

const MyComponent = () => {
  const onScroll = () => {
    console.log('scrolled');
  };
  const { setElement } = useScrollObserver(onScroll);

  return (
    <div>
      <span>Outer Div</span>
      <div ref={setElement}>
        <span>Inner Div</span>
      </div>
    </div>
  );
};
```