Overview

useDisclosure is part of the @usefy ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It manages a boolean "open" state with open / close / toggle handlers, the ergonomic primitive behind modals, drawers, popovers, dropdowns, and accordions.

Features

• open / close / toggle — with stable identities, safe to pass as props or list in effect dependencies
• Transition callbacks — optional onOpen / onClose, fired only on a real state change
• No-op safe — open() while already open (and close() while already closed) does nothing and fires nothing
• StrictMode-safe — callbacks are dispatched from the event handler, never from inside a setState updater, so they never double-fire
• TypeScript-first — full type inference and exported types
• Tiny & tree-shakeable — zero dependencies, published as its own package

Installation

# npm
npm install @usefy/use-disclosure

# yarn
yarn add @usefy/use-disclosure

# pnpm
pnpm add @usefy/use-disclosure

Requires React 18 or 19 (peerDependencies: "react": "^18.0.0 || ^19.0.0").

Quick Start

import { useDisclosure } from "@usefy/use-disclosure";

function Example() {
  const [opened, { open, close, toggle }] = useDisclosure(false);

  return (
    <>
      <button onClick={open}>Open</button>
      <button onClick={toggle}>Toggle</button>
      {opened && (
        <div role="dialog">
          Modal content
          <button onClick={close}>Close</button>
        </div>
      )}
    </>
  );
}

API

const [opened, { open, close, toggle }] = useDisclosure(
  initialState, // boolean — starts open? (default: false)
  options,      // { onOpen?, onClose? } — optional transition callbacks
);

Parameters

| Param | Type | Default | Description | | -------------- | ---------------------- | ------- | ------------------------------------------------------------------ | | initialState | boolean | false | Whether the disclosure starts open. | | options | UseDisclosureOptions | {} | { onOpen?, onClose? } — called on closed→open / open→closed. |

Returns — UseDisclosureReturn

A readonly [opened, handlers] tuple:

• opened: boolean — the current state.
• handlers: { open, close, toggle } — control functions with stable identities.
  • open() — set to true; fires onOpen only on a real closed → open change.
  • close() — set to false; fires onClose only on a real open → closed change.
  • toggle() — flip the state, firing the matching onOpen / onClose.

Example — reacting to transitions

const [opened, handlers] = useDisclosure(false, {
  onOpen: () => trackEvent("drawer_opened"),
  onClose: () => trackEvent("drawer_closed"),
});

Testing

📊 View Detailed Coverage Report (GitHub Pages) — 13 tests, 100% statement coverage.

License

MIT © mirunamu

This package is part of the usefy monorepo.