reakit-utils
    TypeScript icon, indicating that this package has built-in type declarations

    0.15.2 • Public • Published

    reakit-utils

    NPM version

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    getDocument

    Returns element.ownerDocument || document.

    Parameters

    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

    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

    Returns Window

    hasFocus

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

    Parameters

    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

    Examples

    import { hasFocusWithin } from "reakit-utils";
    
    hasFocusWithin(document.getElementById("id"));

    Returns boolean

    isButton

    Checks whether element is a native HTML button element.

    Parameters

    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

    Returns boolean

    isPromise

    Checks whether arg is a promise or not.

    Parameters

    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

    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

    Ponyfill for Element.prototype.matches

    Parameters

    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

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

    Returns Array<Element>

    getFirstFocusableIn

    Returns the first focusable element in container.

    Parameters

    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

    Install

    npm i reakit-utils

    DownloadsWeekly Downloads

    124,811

    Version

    0.15.2

    License

    MIT

    Unpacked Size

    217 kB

    Total Files

    256

    Last publish

    Collaborators

    • diegohaz