Skip to content

Types

Shared TypeScript interfaces and type definitions exported by @diffgazer/keys.

Shared type definitions exported by @diffgazer/keys.

HandlerOptions

Passed to register() in the keyboard context. You won't use this directly — it's the internal representation of UseKeyOptions fields.

ts
interface HandlerOptions {
  allowInInput?: boolean;
  containerRef?: RefObject<HTMLElement | null>;
  focusWithinOnly?: boolean;
  preventDefault?: boolean;
}

UseKeyOptions

Options for useKey.

ts
interface UseKeyOptions {
  enabled?: boolean;
  scope?: string | null;
  allowInInput?: boolean;
  containerRef?: RefObject<HTMLElement | null>;
  focusWithinOnly?: boolean;
  preventDefault?: boolean;
}

UseFocusTrapOptions

Options for useFocusTrap.

ts
interface UseFocusTrapOptions {
  initialFocus?: RefObject<HTMLElement | null>;
  restoreFocus?: boolean;
  enabled?: boolean;
}

RestoreFocusOptions

Options for restoreFocus() and useFocusRestore.

ts
interface RestoreFocusOptions {
  preventScroll?: boolean;
}

UseFocusRestoreOptions

Options for useFocusRestore.

ts
interface UseFocusRestoreOptions extends RestoreFocusOptions {
  enabled?: boolean;
  restoreOnUnmount?: boolean;
  fallback?: HTMLElement | null;
}

UseScrollLockOptions

Options for useScrollLock.

ts
interface UseScrollLockOptions {
  target?: RefObject<HTMLElement | null>;
  enabled?: boolean;
}

NavigationRole

Used by useNavigation and useScopedNavigation to determine which DOM elements are navigable.

ts
type NavigationRole = "radio" | "checkbox" | "option" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "button" | "tab";

VerticalDirection

Returned by getVerticalArrowDirection() and toVerticalBoundaryDirection().

ts
type VerticalDirection = "up" | "down";

BoundaryDirection

Accepted by toVerticalBoundaryDirection().

ts
type BoundaryDirection = "previous" | "next";

KeyHandler

Callback type for keyboard event handlers.

ts
type KeyHandler = (event: KeyboardEvent) => unknown;

Only the exact return value false has special meaning: it declines the matched key and lets the next lower-priority matching handler in the active scope run. Other return values are ignored. When a handler with preventDefault enabled accepts the match (returns anything other than false), event.preventDefault() runs after that handler returns. A declining handler never prevents the default, so native behavior survives until a handler actually handles the key.

DECLINE and Decline

The named sentinel for that decline value, exported so handlers can spell the intent instead of a bare false. The library's own hooks use it.

ts
const DECLINE = false as const;
type Decline = typeof DECLINE;
tsx
import { DECLINE, useKey } from "@diffgazer/keys";

useKey("Escape", (event) => {
  if (!isMine(event.target)) return DECLINE;
  close();
});