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
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.