---
title: useDisclosure
package: '@chakra-ui/hooks'
description:
  'React hook to handle common open and close scenarios in UI components'
---

`useDisclosure` is a custom hook used to help handle common `open`, `close`, or
`toggle` scenarios. It can be used to control feedback component such as
[Modal](/docs/components/overlay/modal),
[AlertDialog](/docs/components/overlay/alert-dialog),
[Drawer](/docs/components/overlay/drawer), etc.

## Import

```js
import { useDisclosure } from '@chakra-ui/react'
```

## Return value

The `useDisclosure` hook returns an object with the following fields:

| Name                 | Type       | Default | Description                                                                               |
| -------------------- | ---------- | ------- | ----------------------------------------------------------------------------------------- |
| `isOpen`             | `boolean`  | `false` | If `true`, it sets the controlled component to its visible state.                         |
| `onClose`            | `function` |         | Callback function to set a falsy value for the `isOpen` parameter.                        |
| `onOpen`             | `function` |         | Callback function to set a truthy value for the `isOpen` parameter.                       |
| `onToggle`           | `function` |         | Callback function to toggle the value of the `isOpen` parameter.                          |
| `getDisclosureProps` | `function` |         | Callback function to retrieve a set of props for the controlled component.                |
| `getButtonProps`     | `function` |         | Callback function to retrieve a set of props for the button that triggers the disclosure. |

## Usage

You can use a combination of the methods and values returned by the hook for
various control of the components affected by the disclosure.

Below is the use of returned fields of the hook without a getter to control the
`Drawer` component on button toggle.

```jsx
function Example() {
  const { isOpen, onOpen, onClose } = useDisclosure()

  return (
    <>
      <Button onClick={onOpen}>Open Drawer</Button>
      <Drawer placement='right' onClose={onClose} isOpen={isOpen}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerHeader borderBottomWidth='1px'>Basic Drawer</DrawerHeader>
          <DrawerBody>
            <p>Some contents...</p>
            <p>Some contents...</p>
            <p>Some contents...</p>
          </DrawerBody>
        </DrawerContent>
      </Drawer>
    </>
  )
}
```

Using the `getDisclosureProps` and `getButtonProps` methods returned by the hook
provides the needed attributes and handlers to the respective component and
button for visibility toggling and accessibility.

The component that uses `getDisclosureProps` receives the following props:

- An `id` (can optionally pass this in as a prop to the hook to render a custom
  value).
- A dynamically rendered `hidden` attribute.

`getDisclosureProps` can directly accept any additional props for the component.

The button that uses `getButtonProps` for toggling receives the following props:

- A dynamically rendered `aria-expanded` attribute to let a screen reader know
  whether the disclosure component is visible.
- The `aria-controls` attribute using the `id` (can optionally pass `id` in as a
  prop to the hook to render a custom value). This lets a screen reader know
  which component is controlled by the button.
- An onClick handler that uses the `onToggle` callback along with any other
  click events passed as an `onClick` prop to `getButtonProps`

`getButtonProps` can also directly accept any additional props for the button.

```jsx
function Basic() {
  const { getDisclosureProps, getButtonProps } = useDisclosure()

  const buttonProps = getButtonProps()
  const disclosureProps = getDisclosureProps()
  return (
    <>
      <Button {...buttonProps}>Toggle Me</Button>
      <Text {...disclosureProps} mt={4}>
        This text is being visibly toggled hidden and shown by the button.
        <br />
        (Inspect these components to see the rendered attributes)
      </Text>
    </>
  )
}
```

## Parameters

The `useDisclosure` hook accepts an optional object with the following
properties:

| Parameter                  | Type       | Description                                                                                                         |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `isOpen (Optional)`        | `boolean`  | If `true`, the controlled component is responsible for changing the visible state via `onClose` and `onOpen` props. |
| `defaultIsOpen (Optional)` | `boolean`  | If `true`, it initially sets the controlled component to its visible state.                                         |
| `onClose (Optional)`       | `function` | Function to set a falsy value for the `isOpen` parameter.                                                           |
| `onOpen (Optional)`        | `function` | Function to set a truthy value for the `isOpen` parameter.                                                          |
| `id (Optional)`            | `string`   | String that allows you to associate the disclosure state with a specific component or element on your page.         |