FocusZone

Provide keyboard navigation via arrow keys using a focus zone.

Examples

Contents

UsageAPIs

Usage

Focus zones can run horizontally or vertically, so make sure your direction follows the flow of your page.

Focus zones will, by default, still allow you to tab through the elements if they have tabIndex set properly. If you want to tab out of your container, like on a tab bar, take a look at focus groups.

APIs

FocusZoneDirection

Horizontal1
number
Vertical2
number

FocusZoneKeyStroke

IgnoreNone1
number
Dont alter the keystroke in any way.
IgnoreParents2
number
All parent focus zones should ignore the keystroke, but it should be processed normally by the current focuszone.
IgnoreAll3
number
All focuszones that receive the keystroke should ignore it.

IFocusZoneContext

directionoptional
The direction of the current context.
focuszoneIdoptional
string
The focuszoneId of the current context should be added to elements through the data-focuszone property for elements that are focusable and should particpate in the focuszone handling.

IFocusZoneProps

activateOnEnterfalse
boolean
Clicks on the currently focused element when Enter is pressed if true
allowArrowOutOfInputsfalse
boolean
If set to true, focus will move out of inputs / text areas when at the start or end of their content
circularNavigation
boolean
If set to true, focus will be able to move from the last element to the first or vice versa.
defaultActiveElement
string | (() => string)
A selector for the element to receive focus when the FocusZone mounts.
direction
The direction that focus moves within the FocusZone. This can be left unsupplied if the FocusZone is using the handleTabKey to navigate the FocusZone exclusively.
disabled
boolean
When set to true, the FocusZone will stop managing focus.
focusGroupProps
IFocusGroupProps & { ref?: React.Ref<FocusGroup> }
If provided, will wrap the FocusZone in a FocusGroup to handle tracking the focused items within the FocusZone.
focusOnMount
boolean
Whether the FocusZone should focus a default element when it mounts or not.
handleTabKey
boolean
When handleTabKey is set to true, the tab and shift/tab keys will act as focuszone navigation keys. NOTE: When the focus zone is set in circular navigation mode, the user wont be able to get focus out of the zone without using the mouse or some other method to move the focus.
includeDefaults
boolean
The focuszone can include all items that are tab stops by default within the focus zone. This is not the default, and the focus zone will only pick up components marked with the focuszone id. This is used to support embedded focus zones.
postprocessKeyStroke
(event: React.KeyboardEvent<HTMLElement>) => FocusZoneKeyStroke
This allows the consumer to intercept keystrokes after they are processed by the focus zone and may prevent this focus zone's parents from acting on the keystroke. This wont effect preventDefault.
preprocessKeyStroke
(event: React.KeyboardEvent<HTMLElement>) => FocusZoneKeyStroke
This allows the consumer to intercept keystrokes before they are processed by the focus zone and may prevent this focus zone or it parents from acting on the keystroke. This wont effect preventDefault.
preventScrollOnFocusfalse
boolean
When set to true, prevents scroll after focus on specific element
selectInputTextOnFocusfalse
boolean }
When true if keyboard controlled focus ends up on a focusable input element than input text is selected automatically so user could replace or delete it's content immediately. Consider making it a default behavior, since it's a default behavior for input elements.
skipHiddenCheckfalse
boolean
If the caller knows that all elements of thie focus zone will be visible. This means they will not have display: none or visibility: hidden css attributes they we can skip this validation. This should be used with care, it will ensure there is not style recalculations done during focus evaluation, but this will break the focus zone if hidden elements exist in the zone.

Loaded FocusZone page