UIBeginnerSSR-safehooks/ui/usePopover.ts

usePopover

Outside click + escape popover.

Import

TypeScript
import { usePopover } from '@/hooks';

API

Signature

usePopover(options?) → disclosure + getTriggerProps

When to use

Use usePopover instead of re-implementing the same pattern in multiple components.

SSR / Next.js

DOM extras (scroll lock, focus trap) run only in effects.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · usePopover
Editor
function Pop() {
  const triggerRef = useRef<HTMLButtonElement>(null);
  const contentRef = useRef<HTMLDivElement>(null);
  const pop = usePopover({ triggerRef, contentRef });

  return (
    <>
      <button ref={triggerRef} {...pop.getTriggerProps()}>Open</button>
      {pop.isOpen && <div ref={contentRef}>Popover</div>}
    </>
  );
}
Preview

Implementation source

Full library source for usePopover — copy into your project when you are not installing a package yet.

hooks/ui/usePopover.ts
import { useCallback } from 'react';
import type { RefObject } from 'react';
import { useDisclosure } from './useDisclosure';
import { useClickOutside } from '../events/useClickOutside';
import { useEscapeKey } from '../events/useEscapeKey';

export interface UsePopoverOptions {
  defaultOpen?: boolean;
  triggerRef?: RefObject<HTMLElement | null>;
  contentRef?: RefObject<HTMLElement | null>;
  closeOnOutsideClick?: boolean;
  closeOnEscape?: boolean;
}

/** Popover open state with outside-click and Escape handling. */
export function usePopover(options: UsePopoverOptions = {}) {
  const {
    defaultOpen = false,
    triggerRef,
    contentRef,
    closeOnOutsideClick = true,
    closeOnEscape = true,
  } = options;

  const disclosure = useDisclosure({ defaultOpen });

  const refs = [triggerRef, contentRef].filter(
    Boolean,
  ) as RefObject<HTMLElement | null>[];

  useClickOutside(
    refs.length > 0 ? refs : ({ current: null } as RefObject<HTMLElement | null>),
    () => {
      if (closeOnOutsideClick && disclosure.isOpen) disclosure.close();
    },
  );

  useEscapeKey(
    () => {
      if (closeOnEscape && disclosure.isOpen) disclosure.close();
    },
    { enabled: closeOnEscape && disclosure.isOpen },
  );

  const getTriggerProps = useCallback(
    () => ({
      onClick: () => disclosure.toggle(),
      'aria-expanded': disclosure.isOpen,
    }),
    [disclosure],
  );

  return { ...disclosure, getTriggerProps };
}

Copy-paste example

usePopover.example.tsx
'use client';

import { useRef } from 'react';
import { usePopover } from '@/hooks';

export function Pop() {
  const triggerRef = useRef<HTMLButtonElement>(null);
  const contentRef = useRef<HTMLDivElement>(null);
  const pop = usePopover({ triggerRef, contentRef });

  return (
    <>
      <button ref={triggerRef} {...pop.getTriggerProps()}>Open</button>
      {pop.isOpen && <div ref={contentRef}>Popover</div>}
    </>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: These are headless — you own the markup and styles.
  • Source of truth: open hooks/ui/usePopover.ts for implementation details