Details

Details is a styled details element for use with the useDetails hook. The useDetails hook returns the open state, a setOpen function to manually change the open state, and getDetailsProps which must be spread onto your Details element in order for Details to get receive the proper behaviors provided by the hook. See Kent Dodd's article on this pattern.

The useDetails hook also takes a few configuration options as parameters which are noted in the table below.

You must use a summary element as your Details trigger button. To style your summary element like a Button, you can use the as prop (see example below).

It's also possible to use the useDetails hook with components other than the Primer Details, such as a custom Details or Modal wrapper in your consuming application. All that matters is that the outer element is a details and it contains a summary for the button that opens and closes the component, and that getDetailsProps is properly spread onto the component rendering your details element.

<State>
  {([]) => {
    const {getDetailsProps} = useDetails({closeOnOutsideClick: true})
    return (
      <Details {...getDetailsProps()}>
        <Button as="summary">Hello</Button>
        This is some content
      </Details>
    )
  }}
</State>

You can use the open state returned from the hook to conditionally render content:

<State>
  {([]) => {
    const {getDetailsProps, open} = useDetails({closeOnOutsideClick: true})
    return (
      <Details {...getDetailsProps()}>
        <Button as="summary">{open ? 'open' : 'close'}</Button>
        This is some content
      </Details>
    )
  }}
</State>

You can also manually show/hide the content using the setOpen function returned from the hook. This can be useful if you have action items in the content of the component such as confirmation buttons:

<State>
  {([]) => {
    const {getDetailsProps, setOpen} = useDetails({closeOnOutsideClick: true})
    return (
      <Details {...getDetailsProps()}>
        <Button as="summary">Delete item</Button>
        Are you sure?
        <Button variant="danger" onClick={() => setOpen(false)}>
          Yes I'm sure
        </Button>
      </Details>
    )
  }}
</State>

In previous versions of Primer React Components, we allowed users to pass in a custom onToggle function. You can do this now by overriding the onToggle function returned in getDetailsProps. Please note that in most cases, you'll want the hook's handling of onToggle to be run as well, so that the internal state is properly updated. To do this, manually call the onToggle handler returned from useDetails before executing your custom onToggle code.

<State>
  {([]) => {
    const {getDetailsProps, open, setOpen} = useDetails({closeOnOutsideClick: true})
    const {onToggle, ...detailsProps} = getDetailsProps()
    const customToggle = e => {
      onToggle(e)
      window.alert('hi')
    }
    return (
      <Details {...detailsProps} onToggle={customToggle}>
        <Button as="summary">{open ? 'Open' : 'Closed'}</Button>
        Hello World
      </Details>
    )
  }}
</State>

Props

Details

SystemStyleObject

useDetails hook configuration options

Values returned by the useDetails hook

Edit this page on GitHub

2 contributors

Last edited by broccolinisoup on March 5, 2023