keys/hooks/use-focus-zone

useFocusZone

provider-dependentfocuszones

Manage focus across multiple zones with arrow key and Tab transitions. Supports controlled and uncontrolled zone state.

useFocusZone models a layout as a set of named zones and moves focus between them on arrow keys or Tab. It tracks which zone is active, optionally drives DOM focus to a target per zone, and hands back getKeyOptions so each zone's own shortcuts only fire while that zone holds focus. It is generic over the zone type — use as const arrays for full inference of zone names.

tsx

1 const { zone, isZone, getKeyOptions } = useFocusZone({2   initial: "sidebar",3   zones: ["sidebar", "main", "footer"] as const,4 })

When to use it

A composite layout (sidebar + main, toolbar + canvas, search + results + preview) where arrow keys or Tab should jump between regions.
A region whose internal keyboard handlers should be gated on that region being active.
Two-zone row patterns — though for "content plus inline actions" rows, reach for the purpose-built useActionRowNavigation, which is built on this hook.

For movement within a single list, use useNavigation or useScopedNavigation. useFocusZone handles movement between regions. See the focus zones guide.

Installation

Requires KeyboardProvider and the @diffgazer/keys package, which is not public on npm yet.

Diffgazer packages are not yet published to npm. Until the first release, pack @diffgazer/ui and @diffgazer/keys from the repository and install those tarballs.

@diffgazer/keys requires no CSS or Tailwind setup.

Parameters

Name	Type	Default	Description
initialrequired	T	—	The initial active zone when in uncontrolled mode.
zonesrequired	readonly T[]	—	All available zone identifiers.
zone	T	—	Controlled zone value. When provided, the hook operates in controlled mode.
onZoneChange	(zone: T) => void	—	Called whenever the active zone changes.
onLeaveZone	(zone: T) => void	—	Called when focus leaves a zone.
onEnterZone	(zone: T) => void	—	Called when focus enters a zone.
transitions	(params: { zone: T; key: "ArrowLeft" \| "ArrowRight" \| "ArrowUp" \| "ArrowDown" }) => T \| null	—	Custom transition function. Return the target zone for a key press, or null to block the transition.
tabCycle	readonly T[]	—	Zone order for Tab/Shift+Tab cycling. When omitted, Tab/Shift+Tab are not handled and follow native browser behavior.
tabCycleScope	"containers" \| "document"	"containers"	Where Tab/Shift+Tab cycling claims the Tab key. "containers" cycles only while focus is inside a registered zone container and declines elsewhere so native Tab proceeds (document-wide only when no containment is resolvable). "document" cycles from anywhere in the document except editable targets, which keep native Tab.
tabCycleBoundary	FocusZoneTargetRef	—	Optional document-scope boundary. When it resolves to an element, Tab is claimed only while focus is inside that element; outside it native Tab proceeds. No effect when omitted or null.
scope	string \| null	—	Keyboard scope name to push while the focus zone is active. Null skips scope registration.
containerRef	RefObject<HTMLElement \| null>	—	Optional DOM subtree used to scope registered focus-zone keys.
focusWithinOnly	boolean	—	When true, focus-zone keys only run while focus is inside containerRef.
allowInInput	boolean	—	Whether focus-zone keys may run when an input-like element has focus.
preventDefault	boolean	—	Default preventDefault behavior inherited by transition keys and getKeyOptions helpers.
enabled	boolean	true	Whether the focus zone hook is active.
focus	{ targets: Partial<Record<T, FocusZoneTarget>>; autoFocus?: boolean; preventScroll?: boolean }	—	Optional DOM focus targets for zone changes. A target may be a ref/function, or a { container, target } pair that skips focus repair while focus is already inside the container. Initial mount does not focus unless autoFocus is true.

Returns

UseFocusZoneReturn<T>Object with zone state and helpers for conditional rendering and key options.

Name	Type	Default	Description
zonerequired	T	—	The currently active zone.
setZonerequired	(zone: T) => void	—	Imperatively set the active zone.
isZonerequired	(...zones: T[]) => boolean	—	Returns true if the current zone matches any of the provided zones.
getKeyOptionsrequired	(zone: T, extra?: UseKeyOptions) => UseKeyOptions	—	Returns UseKeyOptions scoped to a specific zone, merging with optional extra options.
getZonePropsrequired	(zone: T) => { "data-focused": true \| undefined }	—	Returns DOM attributes for a zone's container element. Sets data-focused when the zone is active.

Keyboard behavior

Key	Behavior
Arrow keys	Run `transitions({ zone, key })`; return the target zone to move, or `null` to block. Arrow handling is inert when no `transitions` function is supplied.
`Tab` / `Shift+Tab`	Cycle forward / backward through `tabCycle`. When `tabCycle` is omitted, Tab keeps native browser behavior. `tabCycleScope` controls where the cycle claims the key: `"containers"` (default) only while focus is inside a registered zone container, `"document"` from anywhere except editable targets. In document scope, `tabCycleBoundary` can limit claiming to one DOM subtree.

When the focus option is set, changing zones moves DOM focus to the zone's target (a ref, a getter, or a { container, target } pair). Initial mount does not steal focus unless autoFocus is true. getZoneProps(zone) returns data-focused for styling the active region.

The playground example registers its layout container and a focus target for every panel. Tab therefore changes both the active zone and DOM focus only while focus is inside the example; Tab elsewhere on the page remains native.

Examples

Multi-zone layout navigation

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useFocusZone, useScopedNavigation } from "@diffgazer/keys";4 import { useId, useRef } from "react";5 6 type Zone = "sidebar" | "main";7 8 function Layout() {9   const { zone, isZone } = useFocusZone<Zone>({10     initial: "sidebar",11     zones: ["sidebar", "main"],12     transitions: ({ zone, key }) => {13       if (zone === "sidebar" && key === "ArrowRight") return "main";14       if (zone === "main" && key === "ArrowLeft") return "sidebar";15       return null;16     },17   });18 19   return (20     <div>21       <p>22         <span style={{ fontWeight: zone === "sidebar" ? 700 : 400 }}>Sidebar</span>23         {" / "}24         <span style={{ fontWeight: zone === "main" ? 700 : 400 }}>Main</span>25         {" -- ArrowLeft / ArrowRight switch zones"}26       </p>27       <div style={{ display: "flex", gap: 16 }}>28         <Pane29           title="Sidebar"30           items={["Dashboard", "Settings", "Profile"]}31           active={isZone("sidebar")}32           enabled={zone === "sidebar"}33         />34         <Pane35           title="Main"36           items={["Item A", "Item B", "Item C", "Item D"]}37           active={isZone("main")}38           enabled={zone === "main"}39         />40       </div>41     </div>42   );43 }44 45 function Pane({46   title,47   items,48   active,49   enabled,50 }: {51   title: string;52   items: string[];53   active: boolean;54   enabled: boolean;55 }) {56   const containerRef = useRef<HTMLDivElement>(null);57   const headingId = useId();58 59   const { highlighted, isHighlighted } = useScopedNavigation({60     containerRef,61     role: "option",62     wrap: true,63     enabled,64   });65 66   return (67     <div68       style={{69         minWidth: 160,70         padding: 8,71         borderWidth: 1,72         borderStyle: "solid",73         borderColor: active ? "currentColor" : "transparent",74       }}75     >76       <h4 id={headingId}>{title}</h4>77       <div78         ref={containerRef}79         role="listbox"80         tabIndex={0}81         aria-labelledby={headingId}82         aria-activedescendant={83           highlighted84             ? `pane-${title.toLowerCase()}-${highlighted.toLowerCase().replace(/\s+/g, "-")}`85             : undefined86         }87       >88         {items.map((item) => (89           // biome-ignore lint/a11y/useFocusableInteractive: WAI-ARIA listbox pattern — options stay non-focusable; the listbox container holds focus and aria-activedescendant tracks the active option.90           <div91             key={item}92             id={`pane-${title.toLowerCase()}-${item.toLowerCase().replace(/\s+/g, "-")}`}93             role="option"94             data-value={item}95             aria-selected={isHighlighted(item)}96             style={{ padding: "4px 8px", fontWeight: isHighlighted(item) ? 700 : 400 }}97           >98             {item}99           </div>100         ))}101       </div>102     </div>103   );104 }105 106 export default function UseFocusZoneBasic() {107   return (108     <KeyboardProvider>109       <Layout />110     </KeyboardProvider>111   );112 }113

Tab-cycle regions with focus targets

Preview

tsx

1 "use client";2 3 import { KeyboardProvider, useFocusZone } from "@diffgazer/keys";4 import { useRef } from "react";5 6 type Zone = "search" | "results" | "preview";7 const zones = ["search", "results", "preview"] as const;8 9 function FinderLayout() {10   const searchRef = useRef<HTMLInputElement>(null);11   const resultsRef = useRef<HTMLDivElement>(null);12   const previewRef = useRef<HTMLDivElement>(null);13 14   const { zone, getZoneProps } = useFocusZone<Zone>({15     initial: "search",16     zones,17     // Tab / Shift+Tab cycle through the three regions in order.18     tabCycle: zones,19     allowInInput: true,20     focus: {21       targets: {22         search: searchRef,23         results: resultsRef,24         preview: previewRef,25       },26     },27   });28 29   const paneStyle = (z: Zone) => ({30     flex: 1,31     minWidth: 120,32     padding: 8,33     border: "1px solid currentColor",34     outline: zone === z ? "2px solid currentColor" : "none",35   });36 37   return (38     <div>39       <p>Tab and Shift+Tab cycle Search → Results → Preview. Active zone: {zone}.</p>40       <div style={{ display: "flex", gap: 12 }}>41         <div {...getZoneProps("search")} style={paneStyle("search")}>42           <input43             ref={searchRef}44             aria-label="Search"45             placeholder="Search"46             style={{ width: "100%" }}47           />48         </div>49         <div50           ref={resultsRef}51           tabIndex={-1}52           {...getZoneProps("results")}53           style={paneStyle("results")}54         >55           Results56         </div>57         <div58           ref={previewRef}59           tabIndex={-1}60           {...getZoneProps("preview")}61           style={paneStyle("preview")}62         >63           Preview64         </div>65       </div>66     </div>67   );68 }69 70 export default function UseFocusZoneTabCycle() {71   return (72     <KeyboardProvider>73       <FinderLayout />74     </KeyboardProvider>75   );76 }77

Notes

Generic over zone type

useFocusZone is generic over T extends string. Use `as const` arrays for full type inference of zone names.

Controlled and uncontrolled

Pass zone + onZoneChange for controlled mode, or rely on initial for uncontrolled mode.

Scoped DOM handling

Use containerRef + focusWithinOnly when multiple keyboard regions share a page-level scope.

Requires KeyboardProvider

useFocusZone registers key bindings through the provider context and must be used within a <KeyboardProvider> tree.

Edge cases

Controlled mode. Pass zone + onZoneChange to own the active zone; omit zone and rely on initial for uncontrolled state.
Shared page scope. When several zones share one provider scope, pass containerRef + focusWithinOnly so transitions only fire while focus is inside the layout.
focus with { container, target }. The pair form skips focus repair while focus is already inside container, which avoids yanking focus away from a control the user is interacting with.

Hazard: tabCycle can swallow Tab document-wide. tabCycle registers window-level Tab/Shift+Tab handlers. The cycle is only scoped to the layout when the hook can resolve a containing element — either every cycled zone supplies a focus.targets container, or you pass an explicit containerRef. With containment resolvable, Tab only cycles (and only calls preventDefault) while focus is inside one of those containers; outside them it declines so native Tab keeps reaching the skip link, header controls, toasts, and other tabbable elements. If you configure tabCycle with no focus.targets containers and no containerRef, Tab is intercepted across the whole document for as long as the zone is mounted — a WCAG 2.1.1 hazard. Always anchor every cycled zone to a container.

For screen-level layouts where Tab is deliberately the "switch pane" key everywhere, opt in with tabCycleScope: "document". It makes the intercept explicit rather than accidental: Tab cycles zones from anywhere in the document while the zone's scope is active, moves focus to the active zone's target, and still leaves native Tab intact on editable targets so typing in inputs is never trapped.

Add tabCycleBoundary when document-scope cycling should only apply inside one region, such as a page's <main>. While focus is outside the resolved boundary, native Tab proceeds. Omitting the option or returning null keeps the document-wide behavior.

useActionRowNavigation — a two-zone row built on useFocusZone.
useScopedNavigation — move within a zone once focus lands there.
Focus zones guide — transitions, tab cycling, and focus targets.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.