@maximux13/svelte-roving-ux

Svelte Roving UX

Introduction

This is a Svelte implementation of the roving tabindex UX pattern. It is a simple way to manage focus in a list of items, such as a menu or a list of cards. additionally it allows you to provide a custom keyboard shortcut to interact with the selected item.

Demo

You can find a demo here.

Installation

pnpm install --save @maximux13/svelte-roving-ux

Usage

To use this library in your Svelte project, first import it into your component:

import roving from '@maximux13/svelte-roving-ux';

Then, add the use:roving directive to the parent element of the items you want to make focusable:

<div use:roving>
  <button>Item 1</button>
  <button>Item 2</button>
  <button>Item 3</button>
</div>

This will make all direct child elements focusable. If you want to make only some of the child elements focusable or use other element to control the focus, you can use the target option:

<div use:roving={{ target: 'button:not(.disabled)' }}>
  <button>Item 1</button>
  <button>Item 1</button>
  <button class="disabled">Item 2</button>
</div>

You can also use the startIndex option to set the index of the item that should be selected initially:

<div use:roving={{ startIndex: 1 }}>
  <button>Item 1</button>
  <button>Item 2</button>
  <button>Item 3</button>
</div>

If you want to execute a callback function when an item is selected, you can use the callback option:

<script>
  function callback(item, index, previous, next) {
    console.log(item, index, previous, next);
  }
</script>

<div use:roving={{ callback }}>
  <button>Item 1</button>
  <button>Item 2</button>
  <button>Item 3</button>
</div>

The callback function receives the following parameters:

• item: The selected item
• index: The index of the selected item
• previous: The index of the previously selected item
• next: The index of the next item that will be selected

If you want to use a custom keyboard shortcut to interact with the selected item, you can use the keybindings option:

<script>
  function callback(item, index) {
    console.log(item, index);
  }

  const keybindings = {
    'ctrl+x': callback,
    'alt+y': callback
  };
</script>

<div use:roving={{ keybindings }}>
  <button>Item 1</button>
  <button>Item 2</button>
  <button>Item 3</button>
</div>

The keybindings object has the hotkey as key and the callback function as value. The callback function receives the following parameters:

• item: The selected item
• index: The index of the selected item

Supported modifiers are:

• Alt (or Option) (Mac only) => alt
• Control (or Ctrl) => ctrl
• Meta (or Command) (Mac only) => meta
• Shift => shift

Supported keys are:

• A-Z
• 0-9
• F1-F12
• ArrowUp => up
• ArrowDown => down
• ArrowLeft => left
• ArrowRight => right
• Enter => enter
• Space => space
• Backspace => delete
• Escape => escape | esc
• Meta => meta | cmd | mod

If you consider that a keybinding is missing, please open an issue or submit a pull request.

Options

Option	Type	Default	Description
target	string	null	CSS selector for child elements that should be focusable. If null, all child elements are focusable
startIndex	number	0	Index of the item that should be selected initially
callback	function	null	Callback function that is called when an item is selected. The function receives the item, index, previous and next
keybindings	object	{}	Object with keybindings. The key is the hotkey that is pressed and the value is the callback function

Contributing

We welcome contributions to this project! To get started, please follow these steps:

1. Fork this repository to your own account.
2. Clone your forked repository to your local machine.
3. Create a new branch for your changes.
4. Make your changes and commit them with a descriptive message.
5. Push your changes to your forked repository.
6. Submit a pull request to the main repository.

Please ensure that your code adheres to our coding standards and passes our automated tests before submitting a pull request. We also recommend that you open an issue to discuss your proposed changes before starting work on a pull request.

Thank you for your contributions to this project!

Acknowledgements

This library was inspired by the following libraries:

• roving-ux
• toukey

We would like to thank the authors of these libraries for their contributions to the open source community.

License

This project is licensed under the MIT License.