Balance Logo
Balance
Reckon Design System

Utils

The utils package provides a grab-bag of utility hooks and helpers for React development.
Install
pnpm add @reckon-web/utils
Import usage
import {
noop,
cloneValidElement,
assignRef,
useForkedRef,
useThrottle,
devWarning,
forwardRefWithAs,
hexToRgb,
plural,
makeId,
useId,
useClickOutside,
getContrastText,
useKeyPress,
useScrollLock,
wrapHandlers,
useManagedState
} from '@reckon-web/utils';
  • Code
  • API

Build a great experience even faster with these useful tools and helpers. Import hooks and functions from the utils package:

import utils from '@reckon-web/utils';

Ref management

assignRef

Passes or assigns an arbitrary value to a ref function or object.

let ref = assignRef(functionOrMutableRefObject);

useForkedRef

Passes or assigns a value to multiple refs (typically a DOM node). Useful for dealing with components that need an explicit ref for DOM calculations but also forwards refs assigned by an app.

function Component(props, consumerRef) {
let internalRef = useRef();
let ref = useForkedRef(internalRef, consumerRef);
return <div ref={ref} {...props} />;
}

forwardRefWithAs

React.forwardRef is re-exported from @reckon-web/utils as forwardRefWithAs with different type definitions to work with components that have an as prop. It accepts two type arguments, DefaultElementType and Props.

import { forwardRefWithAs } from '@reckon-web/utils';
type Props = { color: string } & HTMLAttributes<HTMLButtonElement>;
let Button = forwardRefWithAs<'button', Props>(
({ color, as: Tag = 'button', ...props }, ref) => {
return <Tag css={{ color }} ref={ref} {...props} />;
}
);

ID helpers

useId

Autogenerate IDs to facilitate WAI-ARIA and server rendering.

A string can be supplied as an argument to be useId in lieu of the auto-generated ID. This is handy for accepting user-provided prop IDs that need to be deterministic.

function Component(props: { id?: string }) {
// Pass in a user-supplied ID that will be used conditionally if provided
const id = useId(props.id);
return (
<>
<label htmlFor={id}>Label</label>
<input id={id} />
</>
);
}

makeId

Use the makeId helper to prefix an existing ID for compound components.

function Component(props: { id?: string }) {
const id = useId(props.id);
const descriptionId = makeId('description', id);
const inputId = makeId('input', id);
const labelId = makeId('label', id);
return (
<>
<label id={labelId} htmlFor={inputId}>
Label
</label>
<input id={inputId} aria-describedby={descriptionId} />
<div id={descriptionId}>Description</div>
</>
);
}

Color management

hexToRgb

Use the hexToRgb helper for converting hex strings to rgb strings. Pass an optional second argument for opacity.

10% accent background
Open in Playroom

getContrastText

Get the appropriate contrast text color (#000, or #fff) for a given background color.

Contrast text

Event handling

useKeyPress

The useKeyPress hook makes it easy to detect when the user is pressing a specific key on their keyboard. It also provides ways to hook into the up/down handlers, when to bind the handlers, and which element to bind them to.

Alt: Up

useClickOutside

Last click: Outside

wrapHandlers

Wraps a lib-defined event handler and a user-defined event handler, returning a single handler that allows a user to prevent lib-defined handlers from firing.

function Component({ onChange }) {
const handleChange = wrapHandlers(onChange, (event) => {
// internal handling
});
return <input onChange={handleChange} />;
}

Miscellaneous

useScrollLock

Prevent scroll on the <body /> for modal components.

Off

useMediaQuery

The useMediaQuery utility is covered by the theme documentation.

Copyright © 2021 Reckon. Designed and developed in partnership with Thinkmill.