Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add arrow based keyboard navigation to browser extension (#2075)

Leendert de Borst70237e135213
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Items/FolderPill.tsx b/apps/browser-extension/src/entrypoints/popup/components/Items/FolderPill.tsx
index 0e5de68b8..1a2976908 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Items/FolderPill.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Items/FolderPill.tsx
@@ -9,6 +9,8 @@ type FolderWithCount = {
interface IFolderPillProps {
folder: FolderWithCount;
onClick: () => void;
+ isActive?: boolean;
+ optionId?: string;
}
/**
@@ -17,11 +19,18 @@ interface IFolderPillProps {
* Displays a folder as a compact pill/tag that can be clicked to navigate into.
* Designed to be displayed inline with other folder pills.
*/
-const FolderPill: React.FC<IFolderPillProps> = ({ folder, onClick }) => {
+const FolderPill: React.FC<IFolderPillProps> = ({ folder, onClick, isActive = false, optionId }) => {
return (
<button
+ id={optionId}
+ role="option"
+ aria-selected={isActive}
onClick={onClick}
- className="inline-flex items-center gap-1.5 px-3 py-1.5 bg-white dark:bg-gray-700/50 hover:bg-gray-50 dark:hover:bg-gray-600/50 border border-gray-200 dark:border-gray-600 rounded-full text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-orange-500/50"
+ className={`inline-flex items-center gap-1.5 px-3 py-1.5 bg-white dark:bg-gray-700/50 hover:bg-gray-50 dark:hover:bg-gray-600/50 rounded-full text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-orange-500/50 border ${
+ isActive
+ ? 'border-orange-500 dark:border-orange-400 ring-2 ring-orange-500/40'
+ : 'border-gray-200 dark:border-gray-600'
+ }`}
>
<svg
className="w-3.5 h-3.5 text-orange-500 dark:text-orange-400 flex-shrink-0"
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Items/ItemCard.tsx b/apps/browser-extension/src/entrypoints/popup/components/Items/ItemCard.tsx
index c61040050..4bc9ef9b6 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Items/ItemCard.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Items/ItemCard.tsx
@@ -13,6 +13,8 @@ type ItemCardProps = {
showFolderPath?: boolean;
searchTerm?: string;
currentFolderPath?: string[] | null;
+ isActive?: boolean;
+ optionId?: string;
};
/**
@@ -22,7 +24,7 @@ type ItemCardProps = {
* It allows the user to navigate to the item details page when clicked.
*
*/
-const ItemCard: React.FC<ItemCardProps> = ({ item, showFolderPath = false, searchTerm = '', currentFolderPath = null }) => {
+const ItemCard: React.FC<ItemCardProps> = ({ item, showFolderPath = false, searchTerm = '', currentFolderPath = null, isActive = false, optionId }) => {
const { t } = useTranslation();
const navigate = useNavigate();
@@ -101,14 +103,18 @@ const ItemCard: React.FC<ItemCardProps> = ({ item, showFolderPath = false, searc
};
return (
- <li>
+ <li id={optionId} role="option" aria-selected={isActive}>
<button
onClick={() => {
// Build URL with search query parameter if present
const url = searchTerm ? `/items/${item.Id}?returnSearch=${encodeURIComponent(searchTerm)}` : `/items/${item.Id}`;
navigate(url);
}}
- className="w-full p-2 border dark:border-gray-600 rounded flex items-center bg-white dark:bg-gray-800 cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-700 focus:outline-none focus:ring-2 focus:ring-blue-500"
+ className={`w-full p-2 border rounded flex items-center bg-white dark:bg-gray-800 cursor-pointer hover:bg-gray-50 dark:hover:bg-gray-700 focus:outline-none focus:ring-2 focus:ring-blue-500 ${
+ isActive
+ ? 'border-blue-500 dark:border-blue-400 ring-2 ring-blue-500/40'
+ : 'border-gray-200 dark:border-gray-600'
+ }`}
>
<div className="w-8 h-8 mr-2 flex-shrink-0">
<ItemIcon item={item} className="w-8 h-8" />
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Layout/Header.tsx b/apps/browser-extension/src/entrypoints/popup/components/Layout/Header.tsx
index bd4dec105..9342178d2 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Layout/Header.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Layout/Header.tsx
@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo } from 'react';
+import React, { useCallback, useEffect, useMemo } from 'react';
import { useTranslation } from 'react-i18next';
import { useNavigate, useLocation, useSearchParams } from 'react-router-dom';
@@ -86,6 +86,41 @@ const Header: React.FC<HeaderProps> = ({
}
}, [navigate, searchParams, location.pathname]);
+ /**
+ * Keyboard navigation:
+ * - ArrowLeft → back action when focus isn't in a text input.
+ */
+ useEffect(() => {
+ if (!currentRoute?.showBackButton) {
+ return;
+ }
+ /**
+ * Document keydown listener that fires the back action on plain ArrowLeft.
+ */
+ const handler = (e: KeyboardEvent): void => {
+ if (e.defaultPrevented) {
+ return;
+ }
+ if (e.key !== 'ArrowLeft' || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+ return;
+ }
+ const target = e.target;
+ if (target instanceof HTMLElement) {
+ if (target.isContentEditable) {
+ return;
+ }
+ const tag = target.tagName;
+ if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') {
+ return;
+ }
+ }
+ e.preventDefault();
+ handleBack();
+ };
+ document.addEventListener('keydown', handler);
+ return (): void => document.removeEventListener('keydown', handler);
+ }, [currentRoute?.showBackButton, handleBack]);
+
/**
* Handle settings.
*/
diff --git a/apps/browser-extension/src/entrypoints/popup/hooks/useListKeyboardNav.ts b/apps/browser-extension/src/entrypoints/popup/hooks/useListKeyboardNav.ts
new file mode 100644
index 000000000..4ae77acb7
--- /dev/null
+++ b/apps/browser-extension/src/entrypoints/popup/hooks/useListKeyboardNav.ts
@@ -0,0 +1,209 @@
+import { useCallback, useEffect, useState, type RefObject } from 'react';
+
+type ActiveKind = 'item' | 'folder' | null;
+
+interface IUseListKeyboardNavParams {
+ folderCount: number;
+ itemCount: number;
+ searchInputRef: RefObject<HTMLInputElement | null>;
+ onActivateFolder: (index: number) => void;
+ onActivateItem: (index: number) => void;
+ onGoBack: () => void;
+ onClearSearch: () => void;
+}
+
+interface IUseListKeyboardNavReturn {
+ activeKind: ActiveKind;
+ activeIndex: number;
+ itemIdFor: (index: number) => string;
+ folderIdFor: (index: number) => string;
+ activeDescendantId: string | undefined;
+ listboxId: string;
+}
+
+const ID_PREFIX = 'kb-nav';
+
+/**
+ * Keyboard navigation for the items list:
+ * ↓ / ↑ move selection across folder pills + item cards
+ * → open selected item / enter selected folder
+ * ← go up one folder (ignored while typing in the search input)
+ */
+export const useListKeyboardNav = (params: IUseListKeyboardNavParams): IUseListKeyboardNavReturn => {
+ const { folderCount, itemCount, searchInputRef, onActivateFolder, onActivateItem, onGoBack, onClearSearch } = params;
+
+ const [activeKind, setActiveKind] = useState<ActiveKind>(null);
+ const [activeIndex, setActiveIndex] = useState(0);
+
+ // Clamp active selection when the underlying lists shrink (e.g. user types into search).
+ useEffect(() => {
+ if (activeKind === 'item') {
+ if (itemCount === 0) {
+ setActiveKind(null);
+ setActiveIndex(0);
+ } else if (activeIndex >= itemCount) {
+ setActiveIndex(itemCount - 1);
+ }
+ } else if (activeKind === 'folder') {
+ if (folderCount === 0) {
+ setActiveKind(null);
+ setActiveIndex(0);
+ } else if (activeIndex >= folderCount) {
+ setActiveIndex(folderCount - 1);
+ }
+ }
+ }, [itemCount, folderCount, activeKind, activeIndex]);
+
+ const itemIdFor = useCallback((index: number): string => `${ID_PREFIX}-item-${index}`, []);
+ const folderIdFor = useCallback((index: number): string => `${ID_PREFIX}-folder-${index}`, []);
+
+ useEffect(() => {
+ /**
+ * Move virtual selection down across folder row, then item row.
+ */
+ const moveDown = (): void => {
+ if (activeKind === null) {
+ if (folderCount > 0) {
+ setActiveKind('folder');
+ setActiveIndex(0);
+ } else if (itemCount > 0) {
+ setActiveKind('item');
+ setActiveIndex(0);
+ }
+ return;
+ }
+ if (activeKind === 'folder') {
+ if (activeIndex + 1 < folderCount) {
+ setActiveIndex(activeIndex + 1);
+ } else if (itemCount > 0) {
+ setActiveKind('item');
+ setActiveIndex(0);
+ }
+ return;
+ }
+ if (activeIndex + 1 < itemCount) {
+ setActiveIndex(activeIndex + 1);
+ }
+ };
+
+ /**
+ * Move virtual selection up across item row, then folder row. At the topmost
+ * selectable entry (first folder, or first item when there are no folders),
+ * clear the selection and return focus to the search input.
+ */
+ const moveUp = (): void => {
+ if (activeKind === 'item') {
+ if (activeIndex - 1 >= 0) {
+ setActiveIndex(activeIndex - 1);
+ return;
+ }
+ if (folderCount > 0) {
+ setActiveKind('folder');
+ setActiveIndex(folderCount - 1);
+ return;
+ }
+ setActiveKind(null);
+ searchInputRef.current?.focus();
+ return;
+ }
+ if (activeKind === 'folder') {
+ if (activeIndex - 1 >= 0) {
+ setActiveIndex(activeIndex - 1);
+ return;
+ }
+ setActiveKind(null);
+ searchInputRef.current?.focus();
+ }
+ };
+
+ /**
+ * Open the currently selected folder or item.
+ */
+ const activate = (): void => {
+ if (activeKind === 'folder' && activeIndex < folderCount) {
+ onActivateFolder(activeIndex);
+ } else if (activeKind === 'item' && activeIndex < itemCount) {
+ onActivateItem(activeIndex);
+ }
+ };
+
+ /**
+ * Document keydown handler — arrows only.
+ */
+ const handleKeyDown = (e: KeyboardEvent): void => {
+ if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+ return;
+ }
+ if (e.key === 'ArrowDown') {
+ e.preventDefault();
+ moveDown();
+ return;
+ }
+ // Enter mirrors ArrowRight; from an empty selection it opens the first item.
+ if (e.key === 'Enter') {
+ if (activeKind === null && itemCount > 0) {
+ e.preventDefault();
+ onActivateItem(0);
+ return;
+ }
+ if (activeKind !== null) {
+ e.preventDefault();
+ activate();
+ }
+ return;
+ }
+ if (e.key === 'ArrowUp') {
+ /*
+ * ArrowUp inside the search input with text and no list selection clears the
+ * search — useful when the popup auto-prefills the search from the page URL
+ * and the user wants to escape that filter without reaching for the mouse.
+ */
+ const searchInputForUp = searchInputRef.current;
+ if (activeKind === null && e.target === searchInputForUp && (searchInputForUp?.value.length ?? 0) > 0) {
+ e.preventDefault();
+ onClearSearch();
+ return;
+ }
+ e.preventDefault();
+ moveUp();
+ return;
+ }
+ /*
+ * While the user is typing in search and hasn't moved into the list yet,
+ * leave Left/Right alone so the text caret still works. Empty input has no
+ * caret to preserve, so let the shortcut fire (e.g. ArrowLeft inside an empty
+ * folder still goes back).
+ */
+ const searchInput = searchInputRef.current;
+ if (activeKind === null && e.target === searchInput && (searchInput?.value.length ?? 0) > 0) {
+ return;
+ }
+ if (e.key === 'ArrowRight') {
+ e.preventDefault();
+ activate();
+ return;
+ }
+ if (e.key === 'ArrowLeft') {
+ e.preventDefault();
+ onGoBack();
+ }
+ };
+
+ document.addEventListener('keydown', handleKeyDown);
+ return (): void => document.removeEventListener('keydown', handleKeyDown);
+ }, [folderCount, itemCount, activeKind, activeIndex, onActivateFolder, onActivateItem, onGoBack, onClearSearch, searchInputRef]);
+
+ const activeDescendantId =
+ activeKind === 'item' ? itemIdFor(activeIndex)
+ : activeKind === 'folder' ? folderIdFor(activeIndex)
+ : undefined;
+
+ return {
+ activeKind,
+ activeIndex,
+ itemIdFor,
+ folderIdFor,
+ activeDescendantId,
+ listboxId: `${ID_PREFIX}-listbox`,
+ };
+};
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/items/ItemsList.tsx b/apps/browser-extension/src/entrypoints/popup/pages/items/ItemsList.tsx
index 9408bb232..285e40f41 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/items/ItemsList.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/items/ItemsList.tsx
@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
import { useTranslation } from 'react-i18next';
import { useLocation, useNavigate, useParams, useSearchParams } from 'react-router-dom';
@@ -16,6 +16,7 @@ import { useApp } from '@/entrypoints/popup/context/AppContext';
import { useDb } from '@/entrypoints/popup/context/DbContext';
import { useHeaderButtons } from '@/entrypoints/popup/context/HeaderButtonsContext';
import { useLoading } from '@/entrypoints/popup/context/LoadingContext';
+import { useListKeyboardNav } from '@/entrypoints/popup/hooks/useListKeyboardNav';
import { useVaultMutate } from '@/entrypoints/popup/hooks/useVaultMutate';
import { useVaultSync } from '@/entrypoints/popup/hooks/useVaultSync';
import { PopoutUtility } from '@/entrypoints/popup/utils/PopoutUtility';
@@ -123,6 +124,7 @@ const ItemsList: React.FC = () => {
const [showSortMenu, setShowSortMenu] = useState(false);
const [showFolders, setShowFolders] = useState(true);
const { setIsInitialLoading } = useLoading();
+ const searchInputRef = useRef<HTMLInputElement | null>(null);
// Load showFolders preference from storage on mount
useEffect(() => {
@@ -671,6 +673,63 @@ const ItemsList: React.FC = () => {
*/
const hasItemsInFoldersOnly = items.length > 0 && items.every((item: Item) => item.FolderId !== null);
+ /**
+ * Open the Nth item in the current sorted list (ArrowRight on an item).
+ */
+ const handleActivateItem = useCallback((index: number): void => {
+ const item = sortedItems[index];
+ if (!item) {
+ return;
+ }
+ const url = searchTerm ? `/items/${item.Id}?returnSearch=${encodeURIComponent(searchTerm)}` : `/items/${item.Id}`;
+ navigate(url);
+ }, [sortedItems, searchTerm, navigate]);
+
+ /**
+ * Enter the Nth folder (ArrowRight on a folder pill).
+ */
+ const handleActivateFolder = useCallback((index: number): void => {
+ const folder = folders[index];
+ if (!folder) {
+ return;
+ }
+ handleFolderClick(folder.id, folder.name);
+ }, [folders, handleFolderClick]);
+
+ /**
+ * Clear the search input (ArrowUp inside the search field with text).
+ */
+ const handleClearSearch = useCallback((): void => {
+ setSearchTerm('');
+ }, []);
+
+ /**
+ * Go up one folder (ArrowLeft).
+ */
+ const handleGoBack = useCallback((): void => {
+ if (!currentFolderId || !dbContext?.sqliteClient) {
+ return;
+ }
+ const allFolders = dbContext.sqliteClient.folders.getAll();
+ const current = allFolders.find((f: Folder) => f.Id === currentFolderId);
+ const parentFolderId = current?.ParentFolderId ?? null;
+ if (parentFolderId) {
+ navigate(`/items/folder/${parentFolderId}`);
+ } else {
+ navigate('/items');
+ }
+ }, [currentFolderId, dbContext, navigate]);
+
+ const { activeKind, activeIndex, itemIdFor, folderIdFor, activeDescendantId, listboxId } = useListKeyboardNav({
+ folderCount: folders.length,
+ itemCount: sortedItems.length,
+ searchInputRef,
+ onActivateFolder: handleActivateFolder,
+ onActivateItem: handleActivateItem,
+ onGoBack: handleGoBack,
+ onClearSearch: handleClearSearch,
+ });
+
if (isLoading) {
return (
<div className="flex justify-center items-center p-8">
@@ -930,11 +989,17 @@ const ItemsList: React.FC = () => {
{items.length > 0 ? (
<div className="mb-4">
<input
+ ref={searchInputRef}
type="text"
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
placeholder={`${t('content.searchVault')}`}
autoFocus
+ role="combobox"
+ aria-controls={listboxId}
+ aria-expanded={sortedItems.length > 0 || folders.length > 0}
+ aria-activedescendant={activeDescendantId}
+ aria-autocomplete="list"
className="w-full p-2 border dark:border-gray-600 rounded bg-white dark:bg-gray-800 text-gray-900 dark:text-white placeholder-gray-400 dark:placeholder-gray-500 focus:ring-blue-500 focus:border-blue-500"
/>
</div>
@@ -1010,12 +1075,14 @@ const ItemsList: React.FC = () => {
<>
{/* Folders as inline pills - only render wrapper if there are folders OR if we can create subfolders */}
{(folders.length > 0 || canCreateSubfolder) && (
- <div className="flex flex-wrap items-center gap-2 mb-4">
- {folders.map(folder => (
+ <div className="flex flex-wrap items-center gap-2 mb-4" role="listbox" aria-label={t('items.title')}>
+ {folders.map((folder, index) => (
<FolderPill
key={folder.id}
folder={folder}
onClick={() => handleFolderClick(folder.id, folder.name)}
+ isActive={activeKind === 'folder' && activeIndex === index}
+ optionId={folderIdFor(index)}
/>
))}
{canCreateSubfolder && (
@@ -1045,12 +1112,14 @@ const ItemsList: React.FC = () => {
{/* Inside folder: always show subfolders and create button */}
{/* Only render wrapper if there are folders OR if we can create subfolders */}
{!searchTerm && (currentFolderId || showFolders) && (folders.length > 0 || canCreateSubfolder) && (
- <div className="flex flex-wrap items-center gap-2 mb-4">
- {folders.map(folder => (
+ <div className="flex flex-wrap items-center gap-2 mb-4" role="listbox" aria-label={t('items.title')}>
+ {folders.map((folder, index) => (
<FolderPill
key={folder.id}
folder={folder}
onClick={() => handleFolderClick(folder.id, folder.name)}
+ isActive={activeKind === 'folder' && activeIndex === index}
+ optionId={folderIdFor(index)}
/>
))}
{canCreateSubfolder && (
@@ -1083,14 +1152,16 @@ const ItemsList: React.FC = () => {
{/* Items */}
{sortedItems.length > 0 && (
- <ul id="items-list" className="space-y-2">
- {sortedItems.map(item => (
+ <ul id={listboxId} role="listbox" className="space-y-2">
+ {sortedItems.map((item, index) => (
<ItemCard
key={item.Id}
item={item}
showFolderPath={!!searchTerm && !!item.FolderPath}
searchTerm={searchTerm}
currentFolderPath={currentFolderPath}
+ isActive={activeKind === 'item' && activeIndex === index}
+ optionId={itemIdFor(index)}
/>
))}
</ul>