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

• canUseDOM
• isUA
• getDocument
• getWindow
• getActiveElement
• contains
• isButton
• matches
• closest
• isTextField
• getNativeElementType
• isPortalEvent
• isSelfTarget
• createEvent
• fireEvent
• fireBlurEvent
• fireKeyboardEvent
• getNextActiveElementOnBlur
• flatten
• isFocusable
• isTabbable
• getAllFocusableIn
• getFirstFocusableIn
• getAllTabbableIn
• getFirstTabbableIn
• getLastTabbableIn
• getNextTabbableIn
• getPreviousTabbableIn
• getClosestFocusable
• hasFocus
• hasFocusWithin
• ensureFocus
• useSafeLayoutEffect
• useInitialValue
• useLazyRef
• useLiveRef
• useEventCallback
• useForkRef
• useNativeElementType
• useUpdateEffect
• shallowEqual
• toArray
• applyState
• isObject
• isPlainObject
• isPromise
• isEmpty
• isInteger
• removeIndexFromArray
• removeItemFromArray
• omit
• pick
• types

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 : "";

isUA

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

Parameters

• string string

getDocument

Returns element.ownerDocument || document.

Parameters

• element (Element | Document | null)?

Returns Document

getWindow

Returns element.ownerDocument.defaultView || window.

Parameters

• element Element?

Returns Window

getActiveElement

Returns element.ownerDocument.activeElement.

Parameters

• element (Element | Document | null)?

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

isButton

Checks whether element is a native HTML button element.

Parameters

• element {tagName: string, type: string?}

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

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

closest

Ponyfill for Element.prototype.closest

Parameters

• element Element
• selectors K

Examples

import { closest } from "reakit-utils";

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

Returns any

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

getNativeElementType

Returns the native tag name of the passed element. If the element is not provided, the second argument defaultType will be used, but only if it's a string.

Parameters

• element (Element | null)?
• defaultType (string | ComponentType)?

Examples

import { getNativeElementType } from "reakit-utils";

getNativeElementType(document.querySelector("div")); // "div"
getNativeElementType(document.querySelector("button")); // "button"
getNativeElementType(null, "button"); // "button"
getNativeElementType(null, SomeComponent); // undefined

isPortalEvent

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

Parameters

• event SyntheticEvent

Returns boolean

isSelfTarget

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

Parameters

• event SyntheticEvent

Returns boolean

createEvent

Creates an event. Supports IE 11.

Parameters

• element HTMLElement
• type string
• eventInit EventInit?

Examples

import { createEvent } from "reakit-utils";

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

Returns Event

fireEvent

Creates and dispatches an event. Supports IE 11.

Parameters

• element HTMLElement
• type string
• eventInit EventInit

Examples

import { fireEvent } from "reakit-utils";

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

fireBlurEvent

Creates and dispatches a blur event. Supports IE 11.

Parameters

• element HTMLElement
• eventInit FocusEventInit?

Examples

import { fireBlurEvent } from "reakit-utils";

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

fireKeyboardEvent

Creates and dispatches a keyboard event. Supports IE 11.

Parameters

• element HTMLElement
• type string
• eventInit KeyboardEventInit

Examples

import { fireKeyboardEvent } from "reakit-utils";

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

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 (ReactFocusEvent | FocusEvent)

Examples

import { getNextActiveElementOnBlur } from "reakit-utils";

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

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]

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)

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

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.

useSafeLayoutEffect

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

useInitialValue

Returns a value that never changes even if the argument is updated.

Parameters

• value InitialState<T>

Examples

import { useInitialValue } from "reakit-utils";

function Component({ prop }) {
  const initialProp = useInitialValue(prop);
}

useLazyRef

Returns a value that is lazily initiated and never changes.

Parameters

• init function (): T

Examples

import { useLazyRef } from "reakit-utils";

function Component() {
  const set = useLazyRef(() => new Set());
}

useLiveRef

Creates a React.RefObject that is constantly updated with the incoming value.

Parameters

• value T

Examples

import { useLiveRef } from "reakit-utils";

function Component({ prop }) {
  const propRef = useLiveRef(prop);
}

useEventCallback

Creates a memoized callback function that is constantly updated with the incoming callback.

Parameters

• callback T?

Examples

import { useEffect } from "react";
import { useEventCallback } from "reakit-utils";

function Component(props) {
  const onClick = useEventCallback(props.onClick);
  useEffect(() => {}, [onClick]);
}

useForkRef

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

Parameters

• refs ...Array<(Ref<any> | undefined)>

Examples

import { forwardRef, useRef } from "react";
import { useForkRef } from "reakit-utils";

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

useNativeElementType

Returns the native tag name of an element by parsing its ref object. If the second argument defaultType is provided, it's going to be used by default on the first render, before React runs the effects.

Parameters

• ref RefObject<Element>
• defaultType (string | ComponentType)?

Examples

import * as React from "react";
import { useNativeElementType } from "reakit-utils";

function Component(props) {
  const ref = React.useRef();
  // button on the first render, div on the second render
  const type = useNativeElementType(ref, "button");
  return <div ref={ref} {...props} />;
}

useUpdateEffect

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

Parameters

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

shallowEqual

Compares two objects.

Parameters

• a AnyObject?
• b AnyObject?

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

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

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 SetStateAction<T>
• currentValue T

Examples

import { applyState } from "reakit-utils";

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

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

isPromise

Checks whether arg is a promise or not.

Parameters

• arg (T | Promise<T>)

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

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.

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

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

AnyObject

Any object

Type: Record<any, any>

SetState

State hook setter.

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

InitialState

Initial state.

Type: (T | function (): T)

License

MIT © Diego Haz