Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document preventFocusOnOpen prop in useOpenAndCloseFocus and useOverlay hooks #926

Merged
merged 2 commits into from
Feb 6, 2025
Merged

document preventFocusOnOpen prop in useOpenAndCloseFocus and useOverlay hooks #926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7326474
document preventFocusOnOpen prop
ktravers Feb 6, 2025
f87dd24
document prop in useOverlay hook
ktravers Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions content/guides/react/hooks/use-open-and-close-focus.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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>
Expand All @@ -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. |
20 changes: 11 additions & 9 deletions content/guides/react/hooks/use-overlay.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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} />
}

Expand All @@ -41,6 +41,7 @@ const DemoComponent = () => {
initialFocusRef={initialFocusRef}
onEscape={closeOverlay}
onClickOutside={closeOverlay}
preventFocusOnOpen={true}
>
<Button>Button One</Button>
<Button ref={initialFocusRef}>Button Two</Button>
Expand All @@ -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.