alpha

useDisclosure

Provides the behavior and accessibility implementation for a disclosure component.

install	`yarn add @react-aria/disclosure`
version	3.0.0-alpha.0
usage	`import {useDisclosure} from '@react-aria/disclosure'`

View ARIA pattern

API#

useDisclosure(
  props: AriaDisclosureProps,
  state: DisclosureState,
  ref?: RefObject<Element
    |  | null>
): DisclosureAria

Features#

A disclosure is a collapsible section of content. It is composed of a trigger button and a panel that contains the content. useDisclosure can be used to implement these in an accessible way.

Support for mouse, touch, and keyboard interactions to open and close the disclosure
Support for disabled disclosures
Follows the disclosure ARIA pattern, semantically linking the trigger button and panel
Uses hidden="until-found" in supported browsers, enabling find-in-page search support and improved search engine visibility for collapsed content

Anatomy#

A disclosure consists of a trigger button and a panel. Clicking on or pressing Enter or Space while the trigger button is focused toggles the visibility of the panel.

useDisclosure returns props to spread onto the trigger button and panel.

Name	Type	Description
`buttonProps`	`AriaButtonProps`	Props for the disclosure button.
`panelProps`	`HTMLAttributes<HTMLElement>`	Props for the disclosure panel.

State is managed by the useDisclosureState hook in @react-stately/disclosure. The state object should be passed as an option to useDisclosure.

Example#

This example displays a basic disclosure with a button that toggles the visibility of the panel.

import {useDisclosureState} from '@react-stately/disclosure';
import {useDisclosure} from '@react-aria/disclosure';
import {useButton} from '@react-aria/button';

function Disclosure(props) {
  let state = useDisclosureState(props);
  let panelRef = React.useRef<HTMLDivElement | null>(null);
  let triggerRef = React.useRef<HTMLButtonElement | null>(null);
  let { buttonProps: triggerProps, panelProps } = useDisclosure(
    props,
    state,
    panelRef
  );
  let { buttonProps } = useButton(triggerProps, triggerRef);

  return (
    <div className="disclosure">
      <h3>
        <button className="trigger" ref={triggerRef} {...buttonProps}>
          <svg viewBox="0 0 24 24">
            <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
          </svg>
          {props.title}
        </button>
      </h3>
      <div className="panel" ref={panelRef} {...panelProps}>
        <p>
          {props.children}
        </p>
      </div>
    </div>
  );
}

<Disclosure title="System Requirements">
  Details about system requirements here.
</Disclosure>

import {useDisclosureState} from '@react-stately/disclosure';
import {useDisclosure} from '@react-aria/disclosure';
import {useButton} from '@react-aria/button';

function Disclosure(props) {
  let state = useDisclosureState(props);
  let panelRef = React.useRef<HTMLDivElement | null>(null);
  let triggerRef = React.useRef<HTMLButtonElement | null>(
    null
  );
  let { buttonProps: triggerProps, panelProps } =
    useDisclosure(props, state, panelRef);
  let { buttonProps } = useButton(triggerProps, triggerRef);

  return (
    <div className="disclosure">
      <h3>
        <button
          className="trigger"
          ref={triggerRef}
          {...buttonProps}
        >
          <svg viewBox="0 0 24 24">
            <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
          </svg>
          {props.title}
        </button>
      </h3>
      <div className="panel" ref={panelRef} {...panelProps}>
        <p>
          {props.children}
        </p>
      </div>
    </div>
  );
}

<Disclosure title="System Requirements">
  Details about system requirements here.
</Disclosure>

import {useDisclosureState} from '@react-stately/disclosure';
import {useDisclosure} from '@react-aria/disclosure';
import {useButton} from '@react-aria/button';

function Disclosure(
  props
) {
  let state =
    useDisclosureState(
      props
    );
  let panelRef = React
    .useRef<
      | HTMLDivElement
      | null
    >(null);
  let triggerRef = React
    .useRef<
      | HTMLButtonElement
      | null
    >(null);
  let {
    buttonProps:
      triggerProps,
    panelProps
  } = useDisclosure(
    props,
    state,
    panelRef
  );
  let { buttonProps } =
    useButton(
      triggerProps,
      triggerRef
    );

  return (
    <div className="disclosure">
      <h3>
        <button
          className="trigger"
          ref={triggerRef}
          {...buttonProps}
        >
          <svg viewBox="0 0 24 24">
            <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
          </svg>
          {props.title}
        </button>
      </h3>
      <div
        className="panel"
        ref={panelRef}
        {...panelProps}
      >
        <p>
          {props
            .children}
        </p>
      </div>
    </div>
  );
}

<Disclosure title="System Requirements">
  Details about system
  requirements here.
</Disclosure>

Show CSS

.disclosure {
  .trigger {
    background: none;
    border: none;
    box-shadow: none;
    font-weight: bold;
    font-size: 16px;
    display: flex;
    align-items: center;
    gap: 8px;

    svg {
      rotate: 0deg;
      transition: rotate 200ms;
      width: 12px;
      height: 12px;
      fill: none;
      stroke: currentColor;
      stroke-width: 3px;
    }

    &[aria-expanded="true"] svg {
      rotate: 90deg;
    }
  }
}

.panel {
  margin-left: 32px;
}

.disclosure {
  .trigger {
    background: none;
    border: none;
    box-shadow: none;
    font-weight: bold;
    font-size: 16px;
    display: flex;
    align-items: center;
    gap: 8px;

    svg {
      rotate: 0deg;
      transition: rotate 200ms;
      width: 12px;
      height: 12px;
      fill: none;
      stroke: currentColor;
      stroke-width: 3px;
    }

    &[aria-expanded="true"] svg {
      rotate: 90deg;
    }
  }
}

.panel {
  margin-left: 32px;
}

.disclosure {
  .trigger {
    background: none;
    border: none;
    box-shadow: none;
    font-weight: bold;
    font-size: 16px;
    display: flex;
    align-items: center;
    gap: 8px;

    svg {
      rotate: 0deg;
      transition: rotate 200ms;
      width: 12px;
      height: 12px;
      fill: none;
      stroke: currentColor;
      stroke-width: 3px;
    }

    &[aria-expanded="true"] svg {
      rotate: 90deg;
    }
  }
}

.panel {
  margin-left: 32px;
}

Usage#

The following examples show how to use the Disclosure component created in the above example.

Default expansion#

Whether or not the disclosure is expanded or not by default can be set with the defaultExpanded prop.

<Disclosure title="System Requirements" defaultExpanded>
  Details about system requirements here.
</Disclosure>

<Disclosure title="System Requirements" defaultExpanded>
  Details about system requirements here.
</Disclosure>

<Disclosure
  title="System Requirements"
  defaultExpanded
>
  Details about system
  requirements here.
</Disclosure>

Controlled expansion#

Expansion can be controlled using the isExpanded prop, paired with the onExpandedChange event. The onExpandedChange event is fired when the user presses the trigger button.

function ControlledDisclosure(props) {
  let [isExpanded, setExpanded] = React.useState(false);

  return (
    <Disclosure
      title="System Requirements"
      isExpanded={isExpanded}
      onExpandedChange={setExpanded}
    >
      Details about system requirements here.
    </Disclosure>
  );
}

function ControlledDisclosure(props) {
  let [isExpanded, setExpanded] = React.useState(false);

  return (
    <Disclosure
      title="System Requirements"
      isExpanded={isExpanded}
      onExpandedChange={setExpanded}
    >
      Details about system requirements here.
    </Disclosure>
  );
}

function ControlledDisclosure(
  props
) {
  let [
    isExpanded,
    setExpanded
  ] = React.useState(
    false
  );

  return (
    <Disclosure
      title="System Requirements"
      isExpanded={isExpanded}
      onExpandedChange={setExpanded}
    >
      Details about
      system requirements
      here.
    </Disclosure>
  );
}

Disabled#

A disclosure can be disabled with the isDisabled prop. This will disable the trigger button and prevent the panel from being opened or closed.

<Disclosure title="System Requirements" isDisabled>
  Details about system requirements here.
</Disclosure>

<Disclosure title="System Requirements" isDisabled>
  Details about system requirements here.
</Disclosure>

<Disclosure
  title="System Requirements"
  isDisabled
>
  Details about system
  requirements here.
</Disclosure>

Disclosure Group (Accordion)#

See the docs for useDisclosureGroupState in react-stately for an example of a disclosure group.

Name	Type	Description
`isDisabled`	`boolean`	Whether the disclosure is disabled.
`onExpandedChange`	`( (isExpanded: boolean )) => void`	Handler that is called when the disclosure's expanded state changes.
`isExpanded`	`boolean`	Whether the disclosure is expanded (controlled).
`defaultExpanded`	`boolean`	Whether the disclosure is expanded by default (uncontrolled).

Properties

Name	Type	Description
`isExpanded`	`boolean`	Whether the disclosure is currently expanded.

Methods

Method	Description
`setExpanded( (isExpanded: boolean )): void`	Sets whether the disclosure is expanded.
`expand(): void`	Expand the disclosure.
`collapse(): void`	Collapse the disclosure.
`toggle(): void`	Toggles the disclosure's visibility.

Name	Type	Description
`buttonProps`	`AriaButtonProps`	Props for the disclosure button.
`panelProps`	`HTMLAttributes<HTMLElement>`	Props for the disclosure panel.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`ElementType \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Manages state for a disclosure widget. Tracks whether the disclosure is expanded, and provides methods to toggle this state.

useDisclosureState(
  (props: DisclosureProps
)): DisclosureState

Name	Type	Description
`isExpanded`	`boolean`	Whether the disclosure is expanded (controlled).
`defaultExpanded`	`boolean`	Whether the disclosure is expanded by default (uncontrolled).
`onExpandedChange`	`( (isExpanded: boolean )) => void`	Handler that is called when the disclosure expanded state changes.