useKeyboardFocusMode — Vortex Design System

"use client";

import { Button, Stack, useKeyboardFocusMode } from "@vortexlabs/vortex";
import React from "react";

export const KeyboardFocusExample = () => {
  const targetRef = React.useRef<HTMLButtonElement>(null);
  const { activate, deactivate } = useKeyboardFocusMode();

  return (
    <Stack gap={3} align="start">
      <Stack direction="row" gap={2} wrap>
        <Button
          size="sm"
          onClick={() => {
            activate();
            targetRef.current?.focus();
          }}
        >
          Activate
        </Button>
        <Button size="sm" variant="secondary" onClick={deactivate}>
          Deactivate
        </Button>
      </Stack>
      <Button ref={targetRef} size="sm" variant="secondary">
        Focus target
      </Button>
    </Stack>
  );
};

Features

Shows or hides Vortex focus rings.
Works with programmatic focus.
Can pause and resume focus-mode changes.

Use inside VortexProvider; the actions do nothing outside it. The hook takes no arguments.

Call activate() to show focus rings or deactivate() to hide them. Move focus separately with the element's focus() method.

Pause Mode Changes

Call disable() to freeze the current mode, including keyboard and mouse updates. Call enable() to allow changes again.

Mode changes: enabled

"use client";

import { Button, Stack, Text, useKeyboardFocusMode } from "@vortexlabs/vortex";
import React from "react";

export const KeyboardFocusSuspensionExample = () => {
  const { activate, deactivate, disable, enable } = useKeyboardFocusMode();
  const [frozen, setFrozen] = React.useState(false);

  React.useEffect(() => () => enable(), [enable]);

  return (
    <Stack gap={3} align="start">
      <Text as="p">Mode changes: {frozen ? "frozen" : "enabled"}</Text>
      <Stack direction="row" gap={2} wrap>
        <Button
          size="sm"
          onClick={() => {
            activate();
            disable();
            setFrozen(true);
          }}
        >
          Freeze active mode
        </Button>
        <Button size="sm" variant="secondary" onClick={deactivate}>
          Deactivate
        </Button>
        <Button
          size="sm"
          variant="secondary"
          onClick={() => {
            enable();
            setFrozen(false);
          }}
        >
          Enable changes
        </Button>
      </Stack>
    </Stack>
  );
};

Always call enable() when finished, including on unmount. It preserves the current mode; any caller can resume changes.

Accessibility

Key

Description

TabShift+Tab

Move focus and show focus rings unless mode changes are paused.

Keep a visible focus indicator for keyboard users.