| Benchmark | -DOM Fixture | -- Result{' '} - - | -
|---|
+ Arcade machine is an abstraction layer over gamepads for web-based platforms. It handles + directional navigation for the application, and includes rich React bindings for integration + with your application. +
+ ++ Arcade machine works both with keyboards and gamepads. If you have a controller, you can + plug it into your PC now, otherwise you can play with these examples using your keyboard. +
+ +
+ To get started with arcade machine, you need to make two modifications to your application:
+ wrap the root of your application in the ArcRoot HOC, and set a{' '}
+ tabIndex property on all elements that should be focusable.
+
+ tabIndex=0.
+
+ Here's a quick demonstration. You can navigate around the below example with your arrow + keys, or with a connected controlled. +
+ +
+ You can handle focus events using {'. You can specify elements
+ that should be focused after this one (by selector or the actual element), and additionally
+ add handlers that hook into incoming, outgoing, and button press events. This is the base
+ component on which many of the following components are built. The component takes these
+ properties:
+
+ arcFocusLeft
+ |
+
+ undefined | string | HTMLElement
+ |
+ + Element or selector which should be focused when navigating to the left of this + component. + | +
+ arcFocusRight
+ |
+
+ undefined | string | HTMLElement
+ |
+ + Element or selector which should be focused when navigating to the right of this + component. + | +
+ arcFocusUp
+ |
+
+ undefined | string | HTMLElement
+ |
+ + Element or selector which should be focused when navigating to above this component. + | +
+ arcFocusDown
+ |
+
+ undefined | string | HTMLElement
+ |
+ + Element or selector which should be focused when navigating to below this component. + | +
+ onOutgoing
+ |
+
+ onOutgoing?(ev: ArcFocusEvent): void
+ |
+ + Called with an IArcEvent focus is about to leave this element or one of its children. + | +
+ onIncoming
+ |
+
+ onIncoming?(ev: ArcFocusEvent): void
+ |
+ + Called with an IArcEvent focus is about to enter this element or one of its children. + | +
+ onIncoming
+ |
+
+ onIncoming?(ev: ArcEvent): void
+ |
+
+ Triggers when a button is pressed in the element or one of its children. This will
+ fire before the onOutgoing handler, for directional events.
+ |
+
+ Here's an example of using overriding the "next" element. On these boxes, pressing up/down + will instead focus on adjact boxes. Normally, if no focusable element can be found next, it + would do nothing. +
+ +
+ Focus traps are used to force focus to stay within a subset of your application. This is
+ great for use in modals and overlays. You can optionally set the focusIn and{' '}
+ focusOut properties to HTML elements or selectors to specify where focus should
+ be given when entering and leaving the focus trap, respectively.
+
+ focusIn
+ |
+
+ undefined | string | HTMLElement
+ |
+ Element or selector to give focus to when the focus trap is created. | +
+ focusOut
+ |
+
+ undefined | string | HTMLElement
+ |
+ + Element or selector to give focus to when the focus trap is released. If not provided, + the last focused element before the trap was created will be shown. + | +
+ Here, we trap focus inside the modal when it's open. We also use{' '}
+ {` to close the modal when "back" (B on Xbox controllers, or
+ Escape on the keyboard) is pressed.
+
+ Focus areas are sections of the page which act as opaque focusable 'blocks', and then
+ transfer their focus to a child. This is a common pattern seen if you have multiple rows of
+ content, and want focus to transfer to the first element in each row when navigating down
+ between rows. It takes, as its property, a focusIn property, which is a
+ selector or HTML element to give focus to.
+
+ focusIn
+ |
+
+ undefined | string | HTMLElement
+ |
+ Element or selector to give focus to when the focus trap is created. | +
+ In this demo, regardless of where you are in the previous row, focus is always transferred + to the left-most element of each node when you navigate into it. +
+ +
+ Focus exclusion areas can prevent their contents from being focused on. Simple enough. Good
+ if you have content that's loading in or simply disabled. By default, it'll only exclude its
+ direct child node, and it will prevent the entire subtree from being focused on if{' '}
+ deep is set.
+
+ active
+ |
+
+ undefined | boolean
+ |
+ Whether the exclusion is active. Defaults to true if not provided. | +
+ deep
+ |
+
+ undefined | boolean
+ |
+ Whether to exclude the entire subtree contained in this node. | +
+ In this demo, regardless of where you are in the previous row, focus is always transferred + to the left-most element of each node when you navigate into it. +
+ ++ By default, browsers will automatically scroll whenever to the focused element when you use + native focus. We have scrolling functionality built-in in the event you use the virtual + element store (todo: document this), rather than native focus. Our implementation also + supports smooth scrolling out of the box. +
+ +
+ To use arcade machine's scrolling, you wrap your scroll container with the{' '}
+ {` element. By default, it'll scroll vertically, but you can
+ override this via properties.
+
+ vertical
+ |
+
+ undefined | boolean
+ |
+ Whether to scroll vertically, defaults to true. | +
+ horizontal
+ |
+
+ undefined | boolean
+ |
+ Whether to scroll horizontally, defaults to true false. | +
tabIndex on focusable items?
+
+ {tokens.map((line, i) => (
+
+ {line.map((token, key) => (
+
+ ))}
+
+ ))}
+
+ )}
+