document preventFocusOnOpen prop in useOpenAndCloseFocus and useOverl…

…ay hooks (#926) * document preventFocusOnOpen prop Related: primer/react#5636 * document prop in useOverlay hook
primer · Feb 6, 2025 · e845189 · e845189
1 parent 4f249d4
commit e845189
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 18 deletions.
diff --git a/content/guides/react/hooks/use-open-and-close-focus.mdx b/content/guides/react/hooks/use-open-and-close-focus.mdx
@@ -5,14 +5,16 @@ description: A utility Hook that focuses an element when a component is first mo
 
 `useOpenAndCloseFocus` is a utility Hook that manages focusing an element when a component is first mounted, and returns focus to an element on the page when that component unmounts.
 
-If no ref is passed to `initialFocusRef` , the hook focuses the first focusable element inside of the container.
+If no ref is passed to `initialFocusRef`, the hook focuses the first focusable element inside of the container.
+
+If `preventFocusOnOpen` prop is passed, then no focus will be applied when component mounts, even if `initialFocusRef` prop is included. Only initial focus is prevented; focus will still be returned to `returnFocusRef` when component unmounts.
 
 ### Usage
 
 ```javascript live noinline
-const Overlay = ({returnFocusRef, initialFocusRef, children}) => {
+const Overlay = ({returnFocusRef, initialFocusRef, preventFocusOnOpen, children}) => {
   const containerRef = React.useRef(null)
-  useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef})
+  useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef, preventFocusOnOpen})
   return (
     <Box height="200px" ref={containerRef}>
       {children}
@@ -30,7 +32,7 @@ function Component() {
         toggle
       </Button>
       {isOpen && (
-        <Overlay returnFocusRef={returnFocusRef} initialFocusRef={initialFocusRef}>
+        <Overlay returnFocusRef={returnFocusRef} initialFocusRef={initialFocusRef} preventFocusOnOpen={true}>
           <Button>Button One</Button>
           <Button ref={initialFocusRef}>Button Two</Button>
         </Overlay>
@@ -44,8 +46,9 @@ render(<Component />)
 
 #### useOpenAndCloseFocus settings
 
-| Name            | Type                           | Default | Description                                                               |
-| :-------------- | :----------------------------- | :-----: | :------------------------------------------------------------------------ |
-| initialFocusRef | `React.RefObject<HTMLElement>` |         | Optional. The element to focus when the container is mounted on the page. |
-| returnFocusRef  | `React.RefObject<HTMLElement>` |         | Required. The element to focus when the container is unmounted.           |
-| containerRef    | `React.RefObject<HTMLElement>` |         | Required. A ref for the containing element.                               |
+| Name               | Type                           | Default | Description                                                               |
+| :----------------- | :----------------------------- | :-----: | :------------------------------------------------------------------------ |
+| initialFocusRef    | `React.RefObject<HTMLElement>` |         | Optional. The element to focus when the container is mounted on the page. |
+| returnFocusRef     | `React.RefObject<HTMLElement>` |         | Required. The element to focus when the container is unmounted.           |
+| containerRef       | `React.RefObject<HTMLElement>` |         | Required. A ref for the containing element.                               |
+| preventFocusOnOpen | `React.RefObject<HTMLElement>` |         | Optional. When true, prevents focus when container is mounted.            |
diff --git a/content/guides/react/hooks/use-overlay.mdx b/content/guides/react/hooks/use-overlay.mdx
@@ -19,8 +19,8 @@ These behaviors include:
 ### Usage
 
 ```javascript live noinline
-const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {
-  const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})
+const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, preventFocusOnOpen, ...rest}) => {
+  const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef, preventFocusOnOpen})
   return <Box height="200px" bg="green.4" {...overlayProps} {...rest} />
 }
 
@@ -41,6 +41,7 @@ const DemoComponent = () => {
           initialFocusRef={initialFocusRef}
           onEscape={closeOverlay}
           onClickOutside={closeOverlay}
+          preventFocusOnOpen={true}
         >
           <Button>Button One</Button>
           <Button ref={initialFocusRef}>Button Two</Button>
@@ -55,10 +56,11 @@ render(<DemoComponent />)
 
 #### UseOverlaySettings
 
-| Name            | Type                              | Required | Description                                                                                                                           |
-| :-------------- | :-------------------------------- | :------: | :------------------------------------------------------------------------------------------------------------------------------------ |
-| onEscapePress   | `function`                        | required | Function to call when user presses the Escape key                                                                                     |
-| onOutsideClick  | `function`                        | required | Function to call when user clicks outside of the overlay                                                                              |
-| ignoreClickRefs | `React.RefObject<HTMLElement> []` | optional | Refs to click clicks on in the `onOutsideClick` function, useful for ignoring clicks on elements that trigger the overlay visibility. |
-| initialFocusRef | `React.RefObject<HTMLElement>`    | optional | Ref to focus when overlay is mounted.                                                                                                 |
-| returnFocusRef  | `React.RefObject<HTMLElement>`    | required | Ref to focus when overlay is unmounted. Important for accessibility.                                                                  |
+| Name               | Type                              | Required | Description                                                                                                                           |
+| :----------------- | :-------------------------------- | :------: | :------------------------------------------------------------------------------------------------------------------------------------ |
+| onEscapePress      | `function`                        | required | Function to call when user presses the Escape key                                                                                     |
+| onOutsideClick     | `function`                        | required | Function to call when user clicks outside of the overlay                                                                              |
+| ignoreClickRefs    | `React.RefObject<HTMLElement> []` | optional | Refs to click clicks on in the `onOutsideClick` function, useful for ignoring clicks on elements that trigger the overlay visibility. |
+| initialFocusRef    | `React.RefObject<HTMLElement>`    | optional | Ref to focus when overlay is mounted.                                                                                                 |
+| returnFocusRef     | `React.RefObject<HTMLElement>`    | required | Ref to focus when overlay is unmounted. Important for accessibility.                                                                  |
+| preventFocusOnOpen | `boolean`                         | optional | When true, prevents focus when overlay is mounted, even if `initialFocusRef` is present.