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 · usePopoverEditor
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.tsfor implementation details