@fluentui-contrib/react-gamepad-navigation

Gamepad Navigation for Fluent UI React

[!WARNING] These are not production-ready components and should never be used in product. This space is useful for testing new components whose APIs might change before final release.

This package provides gamepad navigation support for Fluent UI Components. Any gaming controller implementing the Gamepad API is supported. Major brand controllers such as Xbox, PlayStation, Nintendo, 8bit, etc. are supported.

This hook calls useArrowNavigationGroup and useFocusableGroup internally. For that reason, 'useGamepadNavigationGroup' hook uses the same API and configuration as those two previous hooks.

In addition to gamepad navigation, arrow key navigation is available by calling this hook, so there is no need to call useArrowNavigationGroup separately.

Installation

yarn add @fluentui-contrib/react-gamepad-navigation

Mappings

| Controller Input | Mapped Behavior | | ---------------- | ------------------------------------- | | 'A' Button | 'Enter' keydown behavior | | 'B' Button | 'Escape' keydown behavior | | 'X' Button | Not supported | | 'Y' Button | Not supported | | Bumpers | Not supported | | Dpad | Arrow navigation (up/down/left/right) | | Left Stick | Arrow navigation (up/down/left/right) | | Right Stick | Not supported | | Triggers | Not supported |

Components Support

Single Elements

| Component | Support | | ---------- | ------------------ | | Button | ✅ Supported | | Checkbox | ✅ Supported | | Combobox | ✅ Supported | | Dropdown | ✅ Supported | | Input | ✅ Supported | | Link | ✅ Supported | | Menu | ✅ Supported | | RadioGroup | ⚠️ Partial Support | | Select | ⛔ Not Supported | | Slider | ⛔ Not Supported | | SpinButton | ⛔ Not Supported | | Switch | ✅ Supported | | Textarea | ✅ Supported |

[!NOTE] There will be no support for select native element, you should use Dropdown or Combobox components instead.

Composed Elements

| Component | Support | | --------------- | ------------------ | | Accordion | ✅ Supported | | Breadcrumb | ✅ Supported | | DataGrid | ✅ Supported | | InteractionTag | ✅ Supported | | SwatchPicker | ✅ Supported | | TabList | ✅ Supported | | TagPicker | ⚠️ Partial Support | | TeachingPopover | ? | | Toolbar | ? | | Tree | ? |

Usage

To import Hook:

import { useGamepadNavigationGroup } from '@fluentui-contrib/react-gamepad-navigation';

Examples

export const SampleApp = () => {
  // attributes for both: Gamepad and Arrow key navigation
  const { gamepadNavDOMAttributes } = useGamepadNavigationGroup();

  return <div {...gamepadNavDOMAttributes}></div>;
};

Options

The default configuration provides the closest behavior to a console navigation experience. However, All the configurations from useArrowNavigationGroup and useFocusableGroup hooks are available as part of the options for useGamepadNavigationGroup

Hook Options

• axis
• circular
• focusFirstElement
• memorizeCurrent
• tabbable
• tabBehavior
• ignoreDefaultKeydown

axis

type axis: 'vertical' | 'horizontal' | 'grid' | 'grid-linear' | 'both';

Default: grid

Focus will navigate vertically, horizontally or in both directions (grid).

circular

type circular: boolean;

Default: false

Focus will cycle to the first/last elements of the group without stopping.

focusFirstElement

type focusFirstElement: boolean;

Default: false

First focusable element in the group will be focused when the group is focused for the first time.

memorizeCurrent

type memorizeCurrent: boolean;

Default: false

Last focused element in the group will be remembered and focused (if still available) when tabbing from outside of the group.

tabbable

type tabbable: boolean;

Default: true

Allow tabbing within the arrow navigation group items.

tabBehavior

type tabBehavior: 'unlimited' | 'limited' | 'limited-trap-focus';

Default: limited-trap-focus

Behavior for the Tab key.

ignoreDefaultKeydown

type ignoreDefaultKeydown: TabsterTypes.FocusableProps['ignoreKeydown'];

Default: {}

Tabster can ignore default handling of keydown events.