reakit-utils

> This is experimental and may have breaking changes in minor versions.

Installation

npm:

``sh
npm i reakit-utils
`

Yarn:

`sh
yarn add reakit-utils
`

API

#### Table of Contents

- applyState
- canUseDOM
- closest
- contains
- createEvent
- createOnKeyDown
- isUA
- ensureFocus
- fireBlurEvent
- fireEvent
- fireKeyboardEvent
- flatten
- getActiveElement
- getDocument
- getNextActiveElementOnBlur
- getWindow
- hasFocus
- hasFocusWithin
- isButton
- isEmpty
- isInteger
- isObject
- isPlainObject
- isPortalEvent
- isPromise
- isSelfTarget
- isTextField
- matches
- normalizePropsAreEqual
- omit
- pick
- removeIndexFromArray
- removeItemFromArray
- shallowEqual
- \_\_deprecatedSplitProps
- splitProps
- tabbable
- toArray
- types
- useForkRef
- useIsomorphicEffect
- useLiveRef
- useSealedState
- useUpdateEffect

$3

Receives a setState argument and calls it with currentValue if it's a
function. Otherwise return the argument as the new value.

#### Parameters

- argument React.SetStateAction<T>
- currentValue T

#### Examples

`javascript
import { applyState } from "reakit-utils";

applyState((value) => value + 1, 1); // 2
applyState(2, 1); // 2
`

$3

It's true if it is running in a browser environment or false if it is not (SSR).

#### Examples

`javascript
import { canUseDOM } from "reakit-utils";

const title = canUseDOM ? document.title : "";
`

$3

Ponyfill for Element.prototype.closest

#### Parameters

- element Element
- selectors string

#### Examples

`javascript
import { closest } from "reakit-utils";

closest(document.getElementById("id"), "div");
// same as
document.getElementById("id").closest("div");
`

$3

Similar to Element.prototype.contains, but a little bit faster when
element is the same as child.

#### Parameters

- parent Element
- child Element

#### Examples

`javascript
import { contains } from "reakit-utils";

contains(document.getElementById("parent"), document.getElementById("child"));
`

Returns boolean

$3

Creates an Event in a way that also works on IE 11.

#### Parameters

- element HTMLElement
- type string
- eventInit EventInit?

#### Examples

`javascript
import { createEvent } from "reakit-utils";

const el = document.getElementById("id");
el.dispatchEvent(createEvent(el, "blur", { bubbles: false }));
`

Returns Event

$3

Returns an onKeyDown handler to be passed to a component.

#### Parameters

- options Options (optional, default {})
- options.keyMap
- options.onKey
- options.stopPropagation
- options.onKeyDown
- options.shouldKeyDown (optional, default ()=>true)
- options.preventDefault (optional, default true)

Returns React.KeyboardEventHandler

$3

Checks if a given string exists in the user agent string.

#### Parameters

- string string

$3

Ensures element will receive focus if it's not already.

#### Parameters

- element HTMLElement
- $1 EnsureFocusOptions (optional, default {})
- $1.preventScroll
- $1.isActive (optional, default hasFocus)

#### Examples

`javascript
import { ensureFocus } from "reakit-utils";

ensureFocus(document.activeElement); // does nothing

const element = document.querySelector("input");

ensureFocus(element); // focuses element
ensureFocus(element, { preventScroll: true }); // focuses element preventing scroll jump

function isActive(el) {
return el.dataset.active === "true";
}

ensureFocus(document.querySelector("[data-active='true']"), { isActive }); // does nothing
`

Returns number requestAnimationFrame call ID so it can be passed to cancelAnimationFrame if needed.

$3

Creates and dispatches a blur event in a way that also works on IE 11.

#### Parameters

- element HTMLElement
- eventInit FocusEventInit?

#### Examples

`javascript
import { fireBlurEvent } from "reakit-utils";

fireBlurEvent(document.getElementById("id"));
`

$3

Creates and dispatches Event in a way that also works on IE 11.

#### Parameters

- element HTMLElement
- type string
- eventInit EventInit

#### Examples

`javascript
import { fireEvent } from "reakit-utils";

fireEvent(document.getElementById("id"), "blur", {
bubbles: true,
cancelable: true,
});
`

$3

Creates and dispatches KeyboardEvent in a way that also works on IE 11.

#### Parameters

- element HTMLElement
- type string
- eventInit KeyboardEventInit

#### Examples

`javascript
import { fireKeyboardEvent } from "reakit-utils";

fireKeyboardEvent(document.getElementById("id"), "keydown", {
key: "ArrowDown",
shiftKey: true,
});
`

$3

Transforms an array with multiple levels into a flattened one.

#### Parameters

- array Array<T>

#### Examples

`javascript
import { flatten } from "reakit-utils";

flatten([0, 1, [2, [3, 4], 5], 6]);
// => [0, 1, 2, 3, 4, 5, 6]
`

$3

Returns element.ownerDocument.activeElement.

#### Parameters

- element (Element \| Document | null)?

$3

Returns element.ownerDocument || document.

#### Parameters

- element (Element \| Document | null)?

Returns Document

$3

Cross-browser method that returns the next active element (the element that
is receiving focus) after a blur event is dispatched. It receives the blur
event object as the argument.

#### Parameters

- event (React.FocusEvent | FocusEvent)

#### Examples

`javascript
import { getNextActiveElementOnBlur } from "reakit-utils";

const element = document.getElementById("id");
element.addEventListener("blur", (event) => {
const nextActiveElement = getNextActiveElementOnBlur(event);
});
`

$3

Returns element.ownerDocument.defaultView || window.

#### Parameters

- element Element?

Returns Window

$3

Checks if element has focus. Elements that are referenced by
aria-activedescendant are also considered.

#### Parameters

- element Element

#### Examples

`javascript
import { hasFocus } from "reakit-utils";

hasFocus(document.getElementById("id"));
`

Returns boolean

$3

Checks if element has focus within. Elements that are referenced by
aria-activedescendant are also considered.

#### Parameters

- element Element

#### Examples

`javascript
import { hasFocusWithin } from "reakit-utils";

hasFocusWithin(document.getElementById("id"));
`

Returns boolean

$3

Checks whether element is a native HTML button element.

#### Parameters

- element Element

#### Examples

`javascript
import { isButton } from "reakit-utils";

isButton(document.querySelector("button")); // true
isButton(document.querySelector("input[type='button']")); // true
isButton(document.querySelector("div")); // false
isButton(document.querySelector("input[type='text']")); // false
isButton(document.querySelector("div[role='button']")); // false
`

Returns boolean

$3

Checks whether arg is empty or not.

#### Parameters

- arg any

#### Examples

`javascript
import { isEmpty } from "reakit-utils";

isEmpty([]); // true
isEmpty(["a"]); // false
isEmpty({}); // true
isEmpty({ a: "a" }); // false
isEmpty(); // true
isEmpty(null); // true
isEmpty(undefined); // true
isEmpty(""); // true
`

Returns boolean

$3

Checks whether arg is an integer or not.

#### Parameters

- arg any

#### Examples

`javascript
import { isInteger } from "reakit-utils";

isInteger(1); // true
isInteger(1.5); // false
isInteger("1"); // true
isInteger("1.5"); // false
`

Returns boolean

$3

Checks whether arg is an object or not.

#### Parameters

- arg any

Returns boolean

$3

Checks whether arg is a plain object or not.

#### Parameters

- arg any

Returns boolean

$3

Returns true if event has been fired within a React Portal element.

#### Parameters

- event React.SyntheticEvent<Element, Event>

Returns boolean

$3

Checks whether arg is a promise or not.

#### Parameters

- arg (T | Promise<T>)

Returns boolean

$3

Returns true if event.target and event.currentTarget are the same.

#### Parameters

- event React.SyntheticEvent

Returns boolean

$3

Check whether the given element is a text field, where text field is defined
by the ability to select within the input, or that it is contenteditable.

#### Parameters

- element HTMLElement

#### Examples

`javascript
import { isTextField } from "reakit-utils";

isTextField(document.querySelector("div")); // false
isTextField(document.querySelector("input")); // true
isTextField(document.querySelector("input[type='button']")); // false
isTextField(document.querySelector("textarea")); // true
isTextField(document.querySelector("div[contenteditable='true']")); // true
`

Returns boolean

$3

- **See:
**

Ponyfill for Element.prototype.matches

#### Parameters

- element Element
- selectors string

Returns boolean

$3

This higher order functions take propsAreEqual function and
returns a new function which normalizes the props.

Normalizing in our case is making sure the propsAreEqual works with
both version 1 (object spreading) and version 2 (state object) state passing.

To achieve this, the returned function in case of a state object
will spread the state object in both prev and \next props.

Other case it just returns the function as is which makes sure
that we are still backward compatible

#### Parameters

- propsAreEqual function (prev: O, next: O): boolean

Returns function (prev: PropsWithAs<O, T>, next: PropsWithAs<O, T>): boolean

$3

Omits specific keys from an object.

#### Parameters

- object T
- paths (ReadonlyArray<K> | Array<K>)

#### Examples

``javascript
import { omit } from "reakit-utils";

omit({ a: "a", b: "b" }, ["a"]); // { b: "b" }
`

Returns Omit<T, K>

$3

Picks specific keys from an object.

#### Parameters

- object T
- paths (ReadonlyArray<K> | Array<K>)

#### Examples

`javascript
import { pick } from "reakit-utils";

pick({ a: "a", b: "b" }, ["a"]); // { a: "a" }
`

$3

Immutably removes an index from an array.

#### Parameters

- array T
- index number

#### Examples

`javascript
import { removeIndexFromArray } from "reakit-utils";

removeIndexFromArray(["a", "b", "c"], 1); // ["a", "c"]
`

Returns Array A new array without the item in the passed index.

$3

Immutably removes an item from an array.

#### Parameters

- array A
- item any

#### Examples

`javascript
import { removeItemFromArray } from "reakit-utils";

removeItemFromArray(["a", "b", "c"], "b"); // ["a", "c"]

// This only works by reference
const obj = {};
removeItemFromArray([obj], {}); // [obj]
removeItemFromArray([obj], obj); // []
`

Returns Array A new array without the passed item.

$3

Compares two objects.

#### Parameters

- objA Record<any, any>?
- objB Record<any, any>?

#### Examples

`javascript
import { shallowEqual } from "reakit-utils";

shallowEqual({ a: "a" }, {}); // false
shallowEqual({ a: "a" }, { b: "b" }); // false
shallowEqual({ a: "a" }, { a: "a" }); // true
shallowEqual({ a: "a" }, { a: "a", b: "b" }); // false
`

Returns boolean

$3

Splits an object (props) into a tuple where the first item is an object
with the passed keys, and the second item is an object with these keys
omitted.

#### Parameters

- props T
- keys (ReadonlyArray<K> | Array<K>)

#### Examples

`javascript
import { splitProps } from "reakit-utils";

splitProps({ a: "a", b: "b" }, ["a"]); // [{ a: "a" }, { b: "b" }]
`

Returns \[any, Omit<T, K>]

Meta

- deprecated: will be removed in version 2

$3

Splits an object (props) into a tuple where the first item
is the state property, and the second item is the rest of the properties.

It is also backward compatible with version 1. If keys are passed then
splits an object (props) into a tuple where the first item is an object
with the passed keys, and the second item is an object with these keys
omitted.

#### Parameters

- props T
- keys (ReadonlyArray<K> | Array<K>) (optional, default [])

#### Examples

`javascript
import { splitProps } from "reakit-utils";

splitProps({ a: "a", b: "b" }, ["a"]); // [{ a: "a" }, { b: "b" }]
`

`javascript
import { splitProps } from "reakit-utils";

splitProps({ state: { a: "a" }, b: "b" }); // [{ a: "a" }, { b: "b" }]
`

Returns \[any, Omit<T, K>]

$3

#### isFocusable

Checks whether element is focusable or not.

##### Parameters

- element Element

##### Examples

`javascript
import { isFocusable } from "reakit-utils";

isFocusable(document.querySelector("input")); // true
isFocusable(document.querySelector("input[tabindex='-1']")); // true
isFocusable(document.querySelector("input[hidden]")); // false
isFocusable(document.querySelector("input:disabled")); // false
`

Returns boolean

#### isTabbable

Checks whether element is tabbable or not.

##### Parameters

- element Element

##### Examples

`javascript
import { isTabbable } from "reakit-utils";

isTabbable(document.querySelector("input")); // true
isTabbable(document.querySelector("input[tabindex='-1']")); // false
isTabbable(document.querySelector("input[hidden]")); // false
isTabbable(document.querySelector("input:disabled")); // false
`

Returns boolean

#### getAllFocusableIn

Returns all the focusable elements in container.

##### Parameters

- container Element

Returns Array<Element>

#### getFirstFocusableIn

Returns the first focusable element in container.

##### Parameters

- container Element

Returns (Element | null)

#### getAllTabbableIn

Returns all the tabbable elements in container, including the container
itself.

##### Parameters

- container Element
- fallbackToFocusable boolean? If true, it'll return focusable elements if there are no tabbable ones.

Returns Array<Element>

#### getFirstTabbableIn

Returns the first tabbable element in container, including the container
itself if it's tabbable.

##### Parameters

- container Element
- fallbackToFocusable boolean? If true, it'll return the first focusable element if there are no tabbable ones.

Returns (Element | null)

#### getLastTabbableIn

Returns the last tabbable element in container, including the container
itself if it's tabbable.

##### Parameters

- container Element
- fallbackToFocusable boolean? If true, it'll return the last focusable element if there are no tabbable ones.

Returns (Element | null)

#### getNextTabbableIn

Returns the next tabbable element in container.

##### Parameters

- container Element
- fallbackToFocusable boolean? If true, it'll return the next focusable element if there are no tabbable ones.

Returns (Element | null)

#### getPreviousTabbableIn

Returns the previous tabbable element in container.

##### Parameters

- container Element
- fallbackToFocusable boolean? If true, it'll return the previous focusable element if there are no tabbable ones.

Returns (Element | null)

#### getClosestFocusable

Returns the closest focusable element.

##### Parameters

- element (T | null)?
- container Element

Returns (Element | null)

$3

Transforms arg into an array if it's not already.

#### Parameters

- arg T

#### Examples

`javascript
import { toArray } from "reakit-utils";

toArray("a"); // ["a"]
toArray(["a"]); // ["a"]
`

$3

#### RenderProp

Render prop type

Type: function (props: P): React.ReactElement<any>

#### As

"as" prop

Type: React.ElementType<P>

#### HTMLAttributesWithRef

Type: any

#### ExtractHTMLAttributes

Returns only the HTML attributes inside P

`ts
type OnlyId = ExtractHTMLAttributes<{ id: string; foo: string }>;
type HTMLAttributes = ExtractHTMLAttributes;
`

Type: Pick<HTMLAttributesWithRef, Extract<any, any>>

#### UnionToIntersection

Transforms "a" | "b" into "a" & "b"

Type: any

#### PropsWithAs

Generic component props with "as" prop

Type: any

#### ArrayValue

Returns the type of the items in an array

Type: any

#### AnyFunction

Any function

Type: function (...args: Array<any>): any

#### SetState

State hook setter.

Type: React.Dispatch<React.SetStateAction<T>>

$3

Merges up to two React Refs into a single memoized function React Ref so you
can pass it to an element.

#### Parameters

- refA React.Ref<any>?
- refB React.Ref<any>?

#### Examples

`javascript
import React from "react";
import { useForkRef } from "reakit-utils";

const Component = React.forwardRef((props, ref) => {
const internalRef = React.useRef();
return