Navigable List

View in Storybook

Explore interactive examples and all component variations in our Storybook.

The NavigableList component provides a keyboard-navigable list with customizable actions and shortcuts. Built with accessibility in mind, it supports arrow key navigation, custom keyboard shortcuts, and flexible item rendering. Perfect for command palettes, file browsers, user lists, and any interface requiring efficient keyboard navigation.

Basic Usage

View in Storybook

Alice Johnson

Bruno Silva

Carlo Rodriguez

Daniel Kim

Monica Chen

File Browser Example

File Browser

document.pdf

2.4 MB

presentation.pptx

5.1 MB

spreadsheet.xlsx

1.8 MB

image.jpg

3.2 MB

video.mp4

45.6 MB

• Use ↑↓ arrows to navigate

• Press V to view, Ctrl+D to download, Delete to remove

Command Palette Style

Command Palette

Open Settings

Configure application preferences

Execute

View Profile

Manage your user profile

Execute

Create Document

Start a new document

Execute

Export Data

Download your data as CSV

Execute

Press Enter to execute selected command

Multiple Actions Example

Project Alpha

Status: ActiveModified: 2 hours ago

Project Beta

Status: DraftModified: 1 day ago

Project Gamma

Status: CompletedModified: 3 days ago

• V: View • E: Edit • S: Settings • Shift+D: Delete

Properties

NavigableList<T>

Property	Type	Description
items	T[]	Array of items to display in the list.
renderItem	(item: T, isSelected: boolean) => ReactNode	Function to render each item. Receives the item and selection state.
actions	RowAction<T>[]	Array of actions available for each item.
className	string	Additional CSS classes for the container.

RowAction<T>

Property	Type	Description
shortcut	Shortcut	Keyboard shortcut configuration.
label	ReactNode	Visual label for the action (can be text, icon, or button).
callback	(item: T) => void	Function called when the action is triggered.

Shortcut

Property	Type	Description
key	string	The key to trigger the action (e.g., 'e', 'Enter', 'Delete').
ctrl?	boolean	Whether Ctrl key must be pressed.
alt?	boolean	Whether Alt key must be pressed.
shift?	boolean	Whether Shift key must be pressed.

Keyboard Navigation

The NavigableList supports comprehensive keyboard navigation:

• Arrow Keys - Navigate up and down through items
• Custom Shortcuts - Execute actions using configured key combinations
• Focus Management - Maintains focus and scroll position automatically
• Modifier Keys - Support for Ctrl, Alt, and Shift combinations

Accessibility

The NavigableList component includes comprehensive accessibility features:

• ARIA Roles - Uses proper listbox and option roles
• Keyboard Navigation - Full keyboard support with arrow keys
• Screen Reader Support - Proper ARIA labels and descriptions
• Focus Management - Clear focus indicators and automatic scrolling
• Selection State - Announces current selection to screen readers
• Action Shortcuts - Keyboard shortcuts are announced with tooltips

Common Use Cases

The NavigableList component is perfect for:

• Command Palettes - Quick action selection with keyboard shortcuts
• File Browsers - Navigate and manage files with keyboard efficiency
• User Lists - Manage users with quick actions
• Project Management - Navigate projects with contextual actions
• Data Tables - Keyboard-friendly data navigation
• Search Results - Navigate search results with actions
• Menu Systems - Create keyboard-navigable menus
• Task Lists - Manage tasks with keyboard shortcuts

Best Practices

1. Clear Actions - Use descriptive labels and intuitive shortcuts
2. Visual Feedback - Provide clear selection and hover states
3. Consistent Shortcuts - Use familiar keyboard conventions
4. Action Grouping - Group related actions together
5. Performance - Virtualize large lists for better performance
6. Accessibility - Test with screen readers and keyboard navigation
7. Responsive Design - Ensure actions work well on different screen sizes
8. Error Handling - Provide feedback for failed actions