Hooks as the headless pattern

A headless hook returns behaviour, never markup — useX() gives you state plus the handlers and props to wire up, and you render whatever you want. “Headless” means the logic has no opinion about the DOM. The hook owns what (open/closed, toggle) and the caller owns how (a <button>, a <details>, a custom card). Start with the minimal shape: state and the actions that change it.

import { useCallback, useState } from "react";

function useDisclosure(initial = false) {
  const [isOpen, setOpen] = useState(initial);
  const open = useCallback(() => setOpen(true), []);
  const close = useCallback(() => setOpen(false), []);
  const toggle = useCallback(() => setOpen((v) => !v), []);
  return { isOpen, open, close, toggle };
}

That alone is reusable across a dialog, a dropdown, an accordion row. Nothing in it knows or cares what element you’ll attach toggle to — which is exactly the point of headless.

Prop-getters are the upgrade that makes a headless hook ergonomic: they bundle the wiring — onClick, aria-expanded, id — so the caller spreads one object instead of remembering five attributes. A getter is a function that returns the props an element needs, and crucially it composes the caller’s own handlers rather than overwriting them.

function useDisclosure(initial = false) {
  const [isOpen, setOpen] = useState(initial);
  const toggle = useCallback(() => setOpen((v) => !v), []);
  const panelId = useId();

  const getButtonProps = useCallback(
    (props: React.ComponentProps<"button"> = {}) => ({
      ...props,
      "aria-expanded": isOpen,
      "aria-controls": panelId,
      onClick: (e: React.MouseEvent<HTMLButtonElement>) => {
        props.onClick?.(e); // caller's handler runs first
        toggle();
      },
    }),
    [isOpen, panelId, toggle],
  );

  const getPanelProps = useCallback(
    (props: React.ComponentProps<"div"> = {}) => ({
      ...props,
      id: panelId,
      hidden: !isOpen,
    }),
    [isOpen, panelId],
  );

  return { isOpen, toggle, getButtonProps, getPanelProps };
}

The props.onClick?.(e) call before toggle() is the detail that separates a real prop-getter from a toy: the caller can pass their own onClick and it still fires. That’s how a headless hook stays composable instead of hijacking the element.

The caller spreads the getters onto its own markup — and the markup is completely free. This is the payoff over render props: no wrapper component sits between the hook and your JSX, so there’s no nesting and no layout the hook forces on you. The same hook drives a button-and-panel, a <details>, or a fully custom design — only the spread targets change.

function FaqItem({ q, a }: { q: string; a: string }) {
  const { getButtonProps, getPanelProps } = useDisclosure();
  return (
    <section>
      <button {...getButtonProps({ className: "faq-trigger" })}>{q}</button>
      <div {...getPanelProps({ className: "faq-panel" })}>{a}</div>
    </section>
  );
}

Notice getButtonProps({ className: "faq-trigger" }) — the caller’s className flows straight through because the getter spreads ...props first. The accessibility wiring (aria-expanded, aria-controls, id, hidden) is handled by the hook; the styling and structure are the caller’s. Behaviour and markup, cleanly split.

Failure mode one: a hook that returns JSX is not a headless hook — it’s a component wearing a use prefix, and it throws away every advantage. The instant your hook returns <div>…</div>, the caller can no longer choose the element, the styling, or the structure; you’re back to a wrapper with none of a component’s clarity. If you want to return UI, write a component. A hook returns data and behaviour — values, handlers, getters — never elements.

// WRONG: this is a component pretending to be a hook
function useDisclosure() {
  const [isOpen, setOpen] = useState(false);
  return <button onClick={() => setOpen((v) => !v)}>{isOpen ? "Hide" : "Show"}</button>;
  // caller can't restyle, can't pick the element, can't compose — headless freedom is gone
}

// RIGHT: return behaviour; the caller renders
function useDisclosure() {
  const [isOpen, setOpen] = useState(false);
  return { isOpen, toggle: () => setOpen((v) => !v) };
}

If you find yourself reaching for JSX inside a hook, that’s the signal you wanted a component all along.