@fluentui-contrib/react-gamepad-navigation v0.1.2
@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-navigationMappings
| 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
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.