Reakit-utils NPM

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

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)} />;
});