reakit-utils

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

Installation

npm:

npm i reakit-utils

Yarn:

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

applyState

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

import { applyState } from "reakit-utils";

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

canUseDOM

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

Examples

import { canUseDOM } from "reakit-utils";

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

closest

Ponyfill for Element.prototype.closest

Parameters

• element Element
• selectors string

Examples

import { closest } from "reakit-utils";

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

contains

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

Parameters

• parent Element
• child Element

Examples

import { contains } from "reakit-utils";

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

Returns boolean

createEvent

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

Parameters

• element HTMLElement
• type string
• eventInit EventInit?

Examples

import { createEvent } from "reakit-utils";

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

Returns Event

createOnKeyDown

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

isUA

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

Parameters

• string string

ensureFocus

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

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.

fireBlurEvent

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

Parameters

• element HTMLElement
• eventInit FocusEventInit?

Examples

import { fireBlurEvent } from "reakit-utils";

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

fireEvent

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

Parameters

• element HTMLElement
• type string
• eventInit EventInit

Examples

import { fireEvent } from "reakit-utils";

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

fireKeyboardEvent

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

Parameters

• element HTMLElement
• type string
• eventInit KeyboardEventInit

Examples

import { fireKeyboardEvent } from "reakit-utils";

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

flatten

Transforms an array with multiple levels into a flattened one.

Parameters

• array Array<T>

Examples

import { flatten } from "reakit-utils";

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

getActiveElement

Returns element.ownerDocument.activeElement.

Parameters

• element (Element | Document | null)?

getDocument

Returns element.ownerDocument || document.

Parameters

• element (Element | Document | null)?

Returns Document

getNextActiveElementOnBlur

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

import { getNextActiveElementOnBlur } from "reakit-utils";

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

getWindow

Returns element.ownerDocument.defaultView || window.

Parameters

• element Element?

Returns Window

hasFocus

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

Parameters

• element Element

Examples

import { hasFocus } from "reakit-utils";

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

Returns boolean

hasFocusWithin

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

Parameters

• element Element

Examples

import { hasFocusWithin } from "reakit-utils";

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

Returns boolean

isButton

Checks whether element is a native HTML button element.

Parameters

• element Element

Examples

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

isEmpty

Checks whether arg is empty or not.

Parameters

• arg any

Examples

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

isInteger

Checks whether arg is an integer or not.

Parameters

• arg any

Examples

import { isInteger } from "reakit-utils";

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

Returns boolean

isObject

Checks whether arg is an object or not.

Parameters

• arg any

Returns boolean

isPlainObject

Checks whether arg is a plain object or not.

Parameters

• arg any

Returns boolean

isPortalEvent

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

Parameters

• event React.SyntheticEvent<Element, Event>

Returns boolean

isPromise

Checks whether arg is a promise or not.

Parameters

• arg (T | Promise<T>)

Returns boolean

isSelfTarget

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

Parameters

• event React.SyntheticEvent

Returns boolean

isTextField

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

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

matches

• **See: https://developer.mozilla.org/en-US/docs/Web/API/Element/matches **

Ponyfill for Element.prototype.matches

Parameters

• element Element
• selectors string

Returns boolean

normalizePropsAreEqual

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

omit

Omits specific keys from an object.

Parameters

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

Examples

import { omit } from "reakit-utils";

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

Returns Omit<T, K>

pick

Picks specific keys from an object.

Parameters

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

Examples

import { pick } from "reakit-utils";

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

removeIndexFromArray

Immutably removes an index from an array.

Parameters

• array T
• index number

Examples

import { removeIndexFromArray } from "reakit-utils";

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

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

removeItemFromArray

Immutably removes an item from an array.

Parameters

• array A
• item any

Examples

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.

shallowEqual

Compares two objects.

Parameters

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

Examples

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

__deprecatedSplitProps

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

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

splitProps

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

import { splitProps } from "reakit-utils";

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

import { splitProps } from "reakit-utils";

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

Returns [any, Omit<T, K>]

tabbable

isFocusable

Checks whether element is focusable or not.

Parameters

• element Element

Examples

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

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)

toArray

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

Parameters

• arg T

Examples

import { toArray } from "reakit-utils";

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

types

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

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

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>>

useForkRef

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

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

const Component = React.forwardRef((props, ref) => {
  const internalRef = React.useRef();
  return <div {...props} ref={useForkRef(internalRef, ref)} />;
});

useIsomorphicEffect

React.useLayoutEffect that fallbacks to React.useEffect on server side rendering.

useLiveRef

A React.Ref that keeps track of the passed value.

Parameters

• value T

Returns React.MutableRefObject<T>

useSealedState

React custom hook that returns the very first value passed to initialState, even if it changes between re-renders.

Parameters

• initialState SealedInitialState<T>

useUpdateEffect

A React.useEffect that will not run on the first render.

Parameters

• effect React.EffectCallback
• deps (ReadonlyArray<any> | undefined)?

License

MIT © Diego Haz