Skip to content

Commit e845189

Browse files
ktraversktravers
authored
document preventFocusOnOpen prop in useOpenAndCloseFocus and useOverlay hooks (#926)
* document preventFocusOnOpen prop Related: primer/react#5636 * document prop in useOverlay hook
1 parent 4f249d4 commit e845189

File tree

2 files changed

+23
-18
lines changed

2 files changed

+23
-18
lines changed

‎content/guides/react/hooks/use-open-and-close-focus.mdx

+12-9
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,16 @@ description: A utility Hook that focuses an element when a component is first mo
55

66
`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.
77

8-
If no ref is passed to `initialFocusRef` , the hook focuses the first focusable element inside of the container.
8+
If no ref is passed to `initialFocusRef`, the hook focuses the first focusable element inside of the container.
9+
10+
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.
911

1012
### Usage
1113

1214
```javascript live noinline
13-
const Overlay = ({returnFocusRef, initialFocusRef, children}) => {
15+
const Overlay = ({returnFocusRef, initialFocusRef, preventFocusOnOpen, children}) => {
1416
const containerRef = React.useRef(null)
15-
useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef})
17+
useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef, preventFocusOnOpen})
1618
return (
1719
<Box height="200px" ref={containerRef}>
1820
{children}
@@ -30,7 +32,7 @@ function Component() {
3032
toggle
3133
</Button>
3234
{isOpen && (
33-
<Overlay returnFocusRef={returnFocusRef} initialFocusRef={initialFocusRef}>
35+
<Overlay returnFocusRef={returnFocusRef} initialFocusRef={initialFocusRef} preventFocusOnOpen={true}>
3436
<Button>Button One</Button>
3537
<Button ref={initialFocusRef}>Button Two</Button>
3638
</Overlay>
@@ -44,8 +46,9 @@ render(<Component />)
4446

4547
#### useOpenAndCloseFocus settings
4648

47-
| Name | Type | Default | Description |
48-
| :-------------- | :----------------------------- | :-----: | :------------------------------------------------------------------------ |
49-
| initialFocusRef | `React.RefObject<HTMLElement>` | | Optional. The element to focus when the container is mounted on the page. |
50-
| returnFocusRef | `React.RefObject<HTMLElement>` | | Required. The element to focus when the container is unmounted. |
51-
| containerRef | `React.RefObject<HTMLElement>` | | Required. A ref for the containing element. |
49+
| Name | Type | Default | Description |
50+
| :----------------- | :----------------------------- | :-----: | :------------------------------------------------------------------------ |
51+
| initialFocusRef | `React.RefObject<HTMLElement>` | | Optional. The element to focus when the container is mounted on the page. |
52+
| returnFocusRef | `React.RefObject<HTMLElement>` | | Required. The element to focus when the container is unmounted. |
53+
| containerRef | `React.RefObject<HTMLElement>` | | Required. A ref for the containing element. |
54+
| preventFocusOnOpen | `React.RefObject<HTMLElement>` | | Optional. When true, prevents focus when container is mounted. |

‎content/guides/react/hooks/use-overlay.mdx

+11-9
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ These behaviors include:
1919
### Usage
2020

2121
```javascript live noinline
22-
const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {
23-
const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})
22+
const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, preventFocusOnOpen, ...rest}) => {
23+
const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef, preventFocusOnOpen})
2424
return <Box height="200px" bg="green.4" {...overlayProps} {...rest} />
2525
}
2626

@@ -41,6 +41,7 @@ const DemoComponent = () => {
4141
initialFocusRef={initialFocusRef}
4242
onEscape={closeOverlay}
4343
onClickOutside={closeOverlay}
44+
preventFocusOnOpen={true}
4445
>
4546
<Button>Button One</Button>
4647
<Button ref={initialFocusRef}>Button Two</Button>
@@ -55,10 +56,11 @@ render(<DemoComponent />)
5556

5657
#### UseOverlaySettings
5758

58-
| Name | Type | Required | Description |
59-
| :-------------- | :-------------------------------- | :------: | :------------------------------------------------------------------------------------------------------------------------------------ |
60-
| onEscapePress | `function` | required | Function to call when user presses the Escape key |
61-
| onOutsideClick | `function` | required | Function to call when user clicks outside of the overlay |
62-
| 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. |
63-
| initialFocusRef | `React.RefObject<HTMLElement>` | optional | Ref to focus when overlay is mounted. |
64-
| returnFocusRef | `React.RefObject<HTMLElement>` | required | Ref to focus when overlay is unmounted. Important for accessibility. |
59+
| Name | Type | Required | Description |
60+
| :----------------- | :-------------------------------- | :------: | :------------------------------------------------------------------------------------------------------------------------------------ |
61+
| onEscapePress | `function` | required | Function to call when user presses the Escape key |
62+
| onOutsideClick | `function` | required | Function to call when user clicks outside of the overlay |
63+
| 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. |
64+
| initialFocusRef | `React.RefObject<HTMLElement>` | optional | Ref to focus when overlay is mounted. |
65+
| returnFocusRef | `React.RefObject<HTMLElement>` | required | Ref to focus when overlay is unmounted. Important for accessibility. |
66+
| preventFocusOnOpen | `boolean` | optional | When true, prevents focus when overlay is mounted, even if `initialFocusRef` is present.

0 commit comments

Comments
 (0)