@empathyco/x-components
Version:
Empathy X Components
88 lines (68 loc) • 3.59 kB
Markdown
title: BaseKeyboardNavigation
# BaseKeyboardNavigation
Base component to handle keyboard navigation for elements inside it. It has a required slot to
include the navigable elements.
## Props
| Name | Description | Type | Default |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| <code>navigationHijacker</code> | An array of TakeNavigationControl objects defining when to<br />take control of the keyboard navigation. | <code>TakeNavigationControl[]</code> | <code>() => [<br /> { xEvent: 'UserPressedArrowKey', moduleName: 'searchBox', direction: 'ArrowDown' },<br />]</code> |
| <code>eventsForDirectionLimit</code> | An EventsForDirectionLimit to emit when the user is already at the furthest element<br />in a direction and tries to keep going on the same direction. | <code>Partial<EventsForDirectionLimit></code> | <code>() => ({ ArrowUp: 'UserReachedEmpathizeTop' })</code> |
## Slots
| Name | Description | Bindings<br />(name - type - description) |
| -------------------- | ---------------------------- | ----------------------------------------- |
| <code>default</code> | (Required) Container content | None |
## Events
An event that the component will emit:
- [`UserReachedEmpathizeTop`](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts):
the event emitted by default when the container reaches its top navigation, but more events can be
emitted for each direction using the `eventsForDirectionLimit` prop.
## Examples
This component has a slot to inject other components inside it. The component expects a required
prop, navigationHijacker, which is an array of objects containing: the xEvent to listen to, the
moduleName in charge of emitting the event and to which direction it should react to; to take
control of the navigation. It has another prop, optional in this case, to emit an xEvent when
reaching the navigation limit in any direction.
### Basic Usage
```vue
<KeyboardNavigation>
<QuerySuggestions/>
</KeyboardNavigation>
```
### Defining multiple conditions to take navigation's control
```vue
<KeyboardNavigation
:navigationHijacker="[
{
xEvent: 'UserPressedArrowKey',
moduleName: 'searchBox',
direction: 'ArrowDown',
},
{
xEvent: 'UserPressedArrowKey',
moduleName: 'facets',
direction: 'ArrowRight',
},
]"
>
<QuerySuggestions/>
</KeyboardNavigation>
```
### Defining events to emit when reaching a navigation limit
```vue
<KeyboardNavigation
:navigationHijacker="[
{
xEvent: 'UserPressedArrowKey',
moduleName: 'searchBox',
direction: 'ArrowDown',
},
]"
:eventsForDirectionLimit="{
ArrowUp: 'UserReachedEmpathizeTop',
}"
>
<QuerySuggestions/>
</KeyboardNavigation>
```