API Reference

useFocusScope()

Creates a scope node in the focus tree and returns a reactive handle. Wrap children with <FocusScope handle={scope}> so nested hooks know their parent.

function useFocusScope(options?: FocusScopeOptions): FocusScopeHandle

FocusScopeOptions

FocusScopeHandle

hasFocus is how a container knows it's in the active focus path — use it for visual feedback, conditional rendering, or any logic that depends on whether the user's attention is inside this scope. isPassive reflects the current navigation mode: when true, this scope has yielded and the parent's bindings are active — surface it so the user knows which level they're navigating.

The navigation methods (next, prev, drillIn, etc.) are stable references, safe to call from event handlers. Call them imperatively, not during render.

FocusScopeHelpers

The subset of FocusScopeHandle passed as the argument to the keybindings factory function.

FocusScope

Sets the parent scope for all children rendered inside it. Children that call useFocusNode() or useFocusScope() without an explicit parent option register under this scope.

function FocusScope({ handle, children }: {
  handle: FocusScopeHandle;
  children: React.ReactNode;
}): JSX.Element

useFocusNode()

Registers a component as a leaf node in the focus tree. Use this when the component itself is the focusable target — a list item, a form field, a button. If the component contains other focusable children, use useFocusScope instead.

function useFocusNode(options?: FocusNodeOptions): FocusNodeHandle

FocusNodeOptions

FocusNodeHandle

The FocusNodeHandle type can be imported for typing component props:

import type { FocusNodeHandle } from 'giggles';

function MyComponent({ focus }: { focus: FocusNodeHandle }) {
  return <Text color={focus.hasFocus ? 'green' : 'white'}>Item</Text>;
}