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

• closest
  • Parameters
  • Examples
• createOnKeyDown
  • Parameters
• cx
  • Parameters
  • Examples
• getActiveElement
  • Parameters
• getDocument
  • Parameters
• hasFocusWithin
  • Parameters
  • Examples
• isButton
  • Parameters
  • Examples
• isEmpty
  • Parameters
  • Examples
• isInteger
  • Parameters
  • Examples
• isObject
  • Parameters
• isPlainObject
  • Parameters
• isPromise
  • Parameters
• mergeRefs
  • Parameters
  • Examples
• omit
  • Parameters
  • Examples
• pick
  • Parameters
  • Examples
• removeIndexFromArray
  • Parameters
  • Examples
• removeItemFromArray
  • Parameters
  • Examples
• splitProps
  • Parameters
  • Examples
• tabbable
  • isFocusable
    • Parameters
    • Examples
  • isTabbable
    • Parameters
    • Examples
  • getAllFocusableIn
    • Parameters
  • getFirstFocusableIn
    • Parameters
  • getAllTabbableIn
    • Parameters
  • getFirstTabbableIn
    • Parameters
  • getLastTabbableIn
    • Parameters
  • getNextTabbableIn
    • Parameters
  • getPreviousTabbableIn
    • Parameters
  • getClosestFocusable
    • Parameters
  • ensureFocus
    • Parameters
    • Examples
• toArray
  • Parameters
  • Examples
• types
  • RenderProp
  • As
  • ElementType
  • HTMLAttributesWithRef
  • ExtractHTMLAttributes
  • UnionToIntersection
  • PickByValue
  • PropsWithAs
  • ArrayValue
  • AnyFunction
• useAllCallbacks
  • Parameters
  • Examples
• useIsomorphicEffect
• useLiveRef
  • Parameters
• usePipe
  • Parameters
• useSealedState
  • Parameters
• useUpdateEffect
  • Parameters
• warning
  • Parameters
  • Examples

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

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

cx

Returns a string with truthy class names separated by space.

Parameters

• classes ...Array<(string | undefined | null | false)>

Examples

import { cx } from "reakit-utils";

const className = cx("a", "b", false, true && "c");

Returns (string | undefined)

getActiveElement

Returns element.ownerDocument.activeElement.

Parameters

• element (Element | Document | null)?

getDocument

Returns element.ownerDocument || window.document.

Parameters

• element (Element | Document | null)?

Returns Document

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

isPromise

Checks whether arg is a promise or not.

Parameters

• arg (T | Promise<T>)

Returns boolean

mergeRefs

Merges multiple React ref props into a single value that can be passed to a component.

Parameters

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

Examples

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

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

Returns (React.Ref<any> | undefined)

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.

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 parent of element.

Parameters

• element T
• 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.ReactType<P>

ElementType

Converts T to its element type

type HTMLDivElement = ElementType<"div">;
type FunctionalComponent = ElementType<() => null>;
type Never = ElementType<"foo">;

Type: any

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

PickByValue

Same as Pick, but with value types instead of key

Type: Pick<T, 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

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

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

warning

Logs messages to the console using console.warn based on a condition.

Parameters

• condition boolean
• messages ...Array<string>

Examples

import { warning } from "reakit-utils";

warning(true, "a", "b"); // console.warn("a\nb")
warning(false, "a", "b"); // does nothing

License

MIT © Diego Haz