Utils

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

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

Ref management

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 @balance-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 '@balance-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.

const { colors } = useTheme();
const foreground = colors.accent;
const background = hexToRgb(foreground, 0.1);
return (
  <div
    style={{
      backgroundColor: background,
      color: foreground,
      display: 'inline-block',
      padding: '4px 12px',
    }}
  >
    10% accent background
  </div>
);

getContrastText

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

const { colors } = useTheme();
const background = colors.accent;
const foreground = getContrastText(background);
return (
  <div
    style={{
      backgroundColor: background,
      color: foreground,
      display: 'inline-block',
      padding: '4px 12px',
    }}
  >
    Contrast text
  </div>
);

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.

const altIsDown = useKeyPress({
  targetKey: 'Alt',
  targetElement: typeof document !== 'undefined' ? document.body : null,
  downHandler: (event) => {
    console.log('Alt down');
  },
  upHandler: (event) => {
    console.log('Alt up');
  },
  listenWhen: true,
});
return (
  <Badge
    tone={altIsDown ? 'positive' : 'critical'}
    label={altIsDown ? 'Alt: Down' : 'Alt: Up'}
  />
);

useClickOutside

const [last, setLast] = useState('Outside');
const ref = React.useRef();
useClickOutside({
  handler: () => setLast('Outside'),
  elements: [ref.current],
  listenWhen: true,
});
return (
  <Box
    background="dim"
    height={120}
    onClick={() => setLast('Inside')}
    ref={ref}
    width={240}
    padding="small"
  >
    <Text>Last click: {last}</Text>
  </Box>
);

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.

const [locked, setLocked] = useState(false);
useScrollLock({ listenWhen: locked });
return (
  <Inline gap="small" alignY="center">
    <ActionButton onClick={() => setLocked((s) => !s)} label="Toggle" />
    <Badge
      tone={locked ? 'critical' : 'positive'}
      label={locked ? 'On' : 'Off'}
    />
  </Inline>
);

useMediaQuery

The useMediaQuery utility is covered by the theme documentation.