This library provides React hooks that serve as a bridge to the @devstore/html-js utility library, enabling imperative DOM manipulation within React's declarative model.

Abstract

The use-html package includes React hooks that allow you to access DOM elements and manipulate them imperatively — beyond what useRef provides. It works with React 18+.

Links

• html-js utils package.
• Wiki documentation.
• Git repository.

Features

• Imperative DOM manipulation after render.
• Automatic cleanup before re-render.
• Ref forwarding support.

For more features see html-js library.

Installation

npm install @devstore/use-html

Getting Started

The simplest way to use use-html is useHtmlRef — it creates a ref and runs a builder callback when the element mounts:

import { useHtmlRef } from '@devstore/use-html';

export const Component: React.FC = () => {
  const ref = useHtmlRef(element => {
    element.focus();
  });
  
  return <input ref={ref} />;
};

The builder can return a cleanup function, which runs before the next render or on unmount:

import { useHtmlRef, HtmlBuilder } from '@devstore/use-html';

const builder: HtmlBuilder<HTMLDivElement> = element => {
  const unsubscriber = addEventListener(element, {
    click: () => console.log('Click')
  });

  return unsubscriber;
};

export const Component: React.FC = () => {
  const ref = useHtmlRef(builder);
  
  return <div ref={ref}>Click me</div>;
};

API

Functions

| Function | Description | Creates Ref | Uses | |---|---|---|---| | useHtmlRef(builder, deps?) | Applies a callback to a newly created ref after paint | ✅ | useEffect | | useHtml(ref, builder, deps?) | Applies a callback to an existing/forwarded ref after paint | ❌ | useEffect | | useLayoutHtmlRef(builder, deps?) | Applies a callback to a newly created ref via useLayoutEffect | ✅ | useLayoutEffect | | useLayoutHtml(ref, builder, deps?) | Applies a callback to an existing/forwarded ref via useLayoutEffect | ❌ | useLayoutEffect | | useHtmlAttributesRef(attrs, deps?) | Applies HTML attributes to a newly created ref after paint | ✅ | useEffect | | useHtmlAttributes(ref, attrs, deps?) | Applies HTML attributes to an existing/forwarded ref after paint | ❌ | useEffect |

Types

| Type | Description | |---|---| | HtmlBuilder<E> | (element: E) => any \| (() => void) — callback that receives an HTMLElement and may return a cleanup function | | RefValue<E> | MutableRefObject<E> \| ForwardedRef<E> \| RefRejectType — acceptable ref types | | RefRejectType | null \| undefined \| false \| 0 \| '' — falsy values that skip hook execution |

useHtmlRef vs useLayoutHtmlRef

useHtmlRef runs the builder after the browser paints — safe for non-blocking operations like focus, scroll, or event listeners.

useLayoutHtmlRef runs the builder before the browser paints, right after DOM updates. Use it when you need to read layout (e.g. getBoundingClientRect) synchronously to avoid visual flicker.

// After paint — safe for most cases
useHtmlRef(element => element.focus());

// Before paint — read layout synchronously
useLayoutHtmlRef(element => {
  const height = element.getBoundingClientRect().height;
  element.style.height = `${height}px`;
});

You can pass multiple builders as an array.

const ref = useHtmlRef([builder1, builder2, builder3]);

Transferred builder need to be memoized or store in variable.

const builder = () => { ... };
/* or const builder = [builder1, builder2, builder3]; */

export const Component: React.FC = () => {
  const ref = useHtmlRef(builder);
  ...
};

You can also pass dependencies as the second argument, if necessary. If deps is omitted, the builder itself is used as the default dependency, so the builder should be memoized or stored in a variable.

const ref = useHtmlRef(builder, [deps1, deps2]);

Ref Forwarding

forwardRef lets a parent component access a child's DOM node. When a component uses forwardRef, the ref comes from outside — use useHtml(ref, builder) instead of useHtmlRef:

export const Component = forwardRef((props, ref) => {
	useHtml(ref, builder);
	...
});

Note: Passing null, undefined, false, 0, or '' as a ref is valid — the hook will skip execution, just like with null.

Lastly, use the html-js utility in builders.