Skip to main

Traverse List Web Component

The Traverse List Web Component Plugin provides a customizable list of items with keyboard navigation functionality.

Installation

You can install the Traverse List Web Component Plugin using npm:

Using pnpm

pnpm add @designbycode/traverse

Using npm

npm install @designbycode/traverse

Using yarn

yarn add @designbycode/traverse

Usage

Add to javascript

import "@designbycode/traverse"

Use in html

Use the <traverse-list> element in your HTML to create the list:


<traverse-list>
  <a href="#" role="menuitem">list 1</a>
  <a href="#" role="menuitem">list 2</a>
  <a href="#" role="menuitem">list 3</a>
</traverse-list>

Attributes

  • loopable (optional): Set to "false" to prevent looping through items using arrow keys. Keyboard Navigation
  • Use the Arrow Up and Arrow Down keys to navigate through the list.
  • Pressing Tab and Shift + Tab will also navigate up and down respectively.

Examples

Basic Usage

Focus on element by clicking it. When traverse-list is active you can use Tab or arrow key traverse through list. by default if last item is focused it will wrap around and loop over list again.


<traverse-list class="block bg-white border border-gray-100 dark:border-gray-800 dark:bg-gray-900 p-2 rounded-lg space-y-2 [&>a]:no-underline">
  <a class="px-4 py-2 block rounded-lg border border-gray-100  dark:border-gray-800 focus:bg-primary-500" href="#" role="menuitem">list 1</a>
  <a class="px-4 py-2 block rounded-lg border border-gray-100  dark:border-gray-800 focus:bg-primary-500" href="#" role="menuitem">list 2</a>
  <a class="px-4 py-2 block rounded-lg border border-gray-100  dark:border-gray-800 focus:bg-primary-500" href="#" role="menuitem">list 3</a>
  <a class="px-4 py-2 block rounded-lg border border-gray-100  dark:border-gray-800 focus:bg-primary-500" href="#" role="menuitem">list 4</a>
  <a class="px-4 py-2 block rounded-lg border border-gray-100  dark:border-gray-800 focus:bg-primary-500" href="#" role="menuitem">list 5</a>
</traverse-list>

Non-loopable List


<traverse-list loopable="false">
  <a href="#" role="menuitem">list 1</a>
  <a href="#" role="menuitem">list 2</a>
  <a href="#" role="menuitem">list 3</a>
</traverse-list>

Attribute of current

Use one of these

  • true (Default)
  • page
  • step
  • location
  • date
  • time
  • false
// "page" | "step" | "location" | "date" | "time" | "false" | "true"
<traverse-list current="step">
  <a href="#" role="menuitem">list 1</a>
  <a href="#" role="menuitem">list 2</a>
  <a href="#" role="menuitem">list 3</a>
</traverse-list>

API

Properties

  • _currentSelectedItem: The index of the currently selected item.
  • _indexPointer: The index of the item with focus.
  • menuItems: A collection of menu items within the component.
  • _current: The value of the "current" attribute.
  • _loopable: A boolean indicating whether looping is enabled.

Methods

  • addEventListeners(): Adds event listeners for keyboard navigation.
  • removeEventListeners(): Removes previously added event listeners.
  • navigateKeys(event): Handles keyboard navigation using Arrow keys and Tab.
  • moveSelectionUp(): Moves selection up within the list.
  • moveSelectionDown(): Moves selection down within the list.
  • markAsCurrent(): Marks the currently selected item with the "aria-current" attribute.

Contributing

Contributions to this plugin are welcome! If you encounter any issues, have feature requests, or want to improve the plugin, feel free to create a pull request or submit an issue on the GitHub repository.

Contributors

contrib

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • This plugin is inspired by the needs of web developers using Tailwind CSS.
  • Special thanks to the Tailwind CSS team for creating such an amazing framework.

©2024 DesignByCode, Inc. All rights reserved.

Design & Developed by DesignByCode