@accessible/use-conditional-focus

---

useConditionalFocus()

npm i @accessible/use-conditional-focus

---

A React hook that will focus elements conditionally. By default this will focus on the first focusable child of the provided root element, but you can optionally include the root as well.

Quick Start

import * as React from 'react'
import useConditionalFocus from '@accessible/use-conditional-focus'

const Component = () => {
  const ref = React.useRef(null)
  const [visible, setVisible] = React.useState(false)
  // Focuses the first focusable child in the `ref` element when
  // visible is `true`
  useConditionalFocus(ref, visible)

  return (
    <div>
      <div ref={ref}>
        // This button will be focused when `visible` is true
        <button onClick={() => setVisible(false)}>Close me</button>
      </div>
      <button onClick={() => setVisible(true)}>Click me</button>
    </div>
  )
}

API

useConditionalFocus(target, shouldFocus, options?)

Arguments

Prop	Type	Default	Required?	Description
target	React.RefObject<T> | T | Window | Document | null		Yes	A React ref, element, window, or document
shouldFocus	boolean	false	Yes	Provide a true value here to focus the first focusable child in the element.
options	UseConditionalFocusOptions	{includeRoot: false, preventScroll: false}	No	See UseConditionalFocusOptions.

UseConditonalFocusOptions

Prop	Type	Default	Required?	Description
includeRoot	boolean	false	No	When true this will try to focus on the root element in addition to its children.
preventScroll	boolean	false	No	When true this will prevent your browser from scrolling the document to bring the newly-focused element into view.

Returns void

LICENSE

MIT

Changelog

3.0.1 (2020-11-27)

Bug Fixes

• 🐛 make it only focus once per condition change (6ffc749)