useOnEscapePress

A utility hook that calls a user-provided function when the 'Escape' key is pressed.

This hook sets up keydown event listener on window.document and executes the user-provided function if these conditions are met:

The Escape key was pressed
The preventDefault method has not yet been called on the event object.

Furthermore, unlike the normal behavior for multiple event listeners existing on the same DOM Node, if multiple useOnEscapePress hooks are active simultaneously, the callbacks will occur in reverse order. In other words, if a parent component and a child component both call useOnEscapePress, when the user presses Escape, the child component's callback will execute, followed by the parent's callback. Each callback has the chance to call .preventDefault() on the event to prevent further callbacks.

Examples

Default

import React from 'react'
import {useOnEscapePress} from '@primer/react'


export default function Default() {
  const [open, setOpen] = React.useState(false)


  useOnEscapePress(() => {
    setOpen(false)
  })


  return (
    <div>
      <button onClick={() => setOpen(!open)}>Toggle a message</button>
      {open && <div>Hit the &quot;Escape&quot; key to hide this message again</div>}
    </div>
  )
}

import React from 'react'
import {useOnEscapePress} from '@primer/react'

export default function Default() {
  const [open, setOpen] = React.useState(false)

  useOnEscapePress(() => {
    setOpen(false)
  })

  return (
    <div>
      <button onClick={() => setOpen(!open)}>Toggle a message</button>
      {open && <div>Hit the &quot;Escape&quot; key to hide this message again</div>}
    </div>
  )
}

With callback dependencies

Similar to useCallback, useOnEscapePress takes a React.DependencyList as its second argument. These are the dependencies used to memoize the callback. Failing to provide the correct dependency list can result in degraded performance. If this argument is omitted, we will assume that the callback is already memoized.

import React from 'react'
import {useOnEscapePress} from '@primer/react'


export default function CallbackDependencies() {
  const [open, setOpen] = React.useState(false)
  const [escapeEnabled, setEscapeEnabled] = React.useState(false)


  useOnEscapePress(() => {
    if (escapeEnabled) {
      setOpen(false)
    }
  }, [escapeEnabled])


  return (
    <>
      <div style={{alignItems: 'flex-start', display: 'flex', flexDirection: 'column', gap: '1rem'}}>
        <button
          onClick={() => {
            setEscapeEnabled(!escapeEnabled)
          }}
        >
          {escapeEnabled ? 'Disable' : 'Enable'} useOnEscapePress behavior
        </button>
        {escapeEnabled ? <button onClick={() => setOpen(!open)}>Toggle a message</button> : null}
      </div>
      {open && <div>Hit the &quot;Escape&quot; key to hide this message again</div>}
    </>
  )
}

import React from 'react'
import {useOnEscapePress} from '@primer/react'

export default function CallbackDependencies() {
  const [open, setOpen] = React.useState(false)
  const [escapeEnabled, setEscapeEnabled] = React.useState(false)

  useOnEscapePress(() => {
    if (escapeEnabled) {
      setOpen(false)
    }
  }, [escapeEnabled])

  return (
    <>
      <div style={{alignItems: 'flex-start', display: 'flex', flexDirection: 'column', gap: '1rem'}}>
        <button
          onClick={() => {
            setEscapeEnabled(!escapeEnabled)
          }}
        >
          {escapeEnabled ? 'Disable' : 'Enable'} useOnEscapePress behavior
        </button>
        {escapeEnabled ? <button onClick={() => setOpen(!open)}>Toggle a message</button> : null}
      </div>
      {open && <div>Hit the &quot;Escape&quot; key to hide this message again</div>}
    </>
  )
}

API

Loading data for useOnEscapePress...

useOverlay