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
• closest
• contains
• createEvent
• createKeyboardEvent
• createOnKeyDown
• fireEvent
• fireKeyboardEvent
• flatten
• getActiveElement
• getDefaultView
• getDocument
• getNextActiveElementOnBlur
• hasFocusWithin
• isButton
• isEmpty
• isInteger
• isObject
• isPlainObject
• isPortalEvent
• isPromise
• isSelfTarget
• isTextField
• matches
• omit
• pick
• removeIndexFromArray
• removeItemFromArray
• shallowEqual
• splitProps
• tabbable
• toArray
• types
• useAllCallbacks
• useForkRef
• useIsomorphicEffect
• useLiveRef
• usePipe
• 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

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.

Parameters

• parent Element
• child Element

Returns boolean

createEvent

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

Parameters

• element HTMLElement
• type string
• eventInit EventInit (optional, default {})

Examples

import { createEvent } from "reakit-utils";

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

Returns Event

createKeyboardEvent

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

Parameters

• element HTMLElement
• type string
• eventInit KeyboardEventInit (optional, default {})

Examples

import { createKeyboardEvent } from "reakit-utils";

const el = document.getElementById("id");
el.dispatchEvent(createKeyboardEvent(el, "keydown", { key: "ArrowDown" }));

Returns KeyboardEvent

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

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

getDefaultView

Returns element.ownerDocument.defaultView || window.

Parameters

• element Element?

Returns Window

getDocument

Returns element.ownerDocument || window.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);
  ...
});

hasFocusWithin

Checks if element has focus.

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 or not.

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

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

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

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 A
• idx 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

splitProps

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

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)

ensureFocus

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

Parameters

• element HTMLElement
• $1 EnsureFocusOptions (optional, default {})
  • $1.isActive (optional, default defaultIsActive)
  • $1.preventScroll

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.

toArray

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

Parameters

• arg any

Examples

import { toArray } from "reakit-utils";

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

Returns Array<any>

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

useAllCallbacks

React custom hook that combines multiple callbacks into one.

Parameters

• callbacks ...Array<(AnyFunction | null | undefined)>

Examples

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

function Component(props) {
  const onClick = () => {};
  return (
    <button onClick={useAllCallbacks(onClick, props.onClick)}>Button</button>
  );
}

Returns AnyFunction

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>

usePipe

A React custom hook similar to useAllCallbacks, but it'll pass the returned value from a function to the next function.

Parameters

• fns ...Array<(AnyFunction | null | undefined)>

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