Keyboard navigation implementation for website (WCAG)

Keyboard Navigation Implementation (WCAG)

Keyboard navigation is a WCAG 2.1 requirement (Success Criterion 2.1.1): all website functions must be accessible via keyboard without a mouse. This is critical for users with motor impairments, screen reader users, and professionals who prefer keyboard navigation.

Basic Navigation Keys

Focus Visibility

WCAG SC 2.4.7 requires a visible focus indicator. Removing outline without replacement is a violation.

/* Don't do this */
*:focus {
    outline: none;
}

/* Good custom focus style */
:focus-visible {
    outline: 3px solid #0066CC;
    outline-offset: 2px;
    border-radius: 2px;
}

/* For interactive elements */
.btn:focus-visible {
    outline: 3px solid #0066CC;
    box-shadow: 0 0 0 6px rgba(0, 102, 204, 0.2);
}

/* Hide only on mouse click, keep on Tab */
:focus:not(:focus-visible) {
    outline: none;
}

Focus Order (tabindex)

Natural DOM order should match visual order. Avoid manipulating tabindex with positive values.

<!-- Good: DOM order matches visual order -->
<button tabindex="0">Button 1</button>
<button tabindex="0">Button 2</button>

<!-- Bad: positive tabindex creates confusion -->
<button tabindex="3">Button 1</button>
<button tabindex="1">Button 2</button>

<!-- tabindex="-1": element can receive focus programmatically but not via Tab -->
<div id="modal" tabindex="-1" role="dialog">...</div>

Custom Components

Native <button>, <a>, <input> work with keyboard automatically. Custom components need explicit keyboard support:

// Custom button — should work like <button>
function CustomButton({ onClick, children, disabled }) {
    const handleKeyDown = (e) => {
        if (e.key === 'Enter' || e.key === ' ') {
            e.preventDefault();
            onClick?.();
        }
    };

    return (
        <div
            role="button"
            tabIndex={disabled ? -1 : 0}
            onClick={onClick}
            onKeyDown={handleKeyDown}
            aria-disabled={disabled}
        >
            {children}
        </div>
    );
}

// Better — use native <button>
function BetterButton({ onClick, children, disabled }) {
    return (
        <button onClick={onClick} disabled={disabled}>
            {children}
        </button>
    );
}

Dropdown Menu (keyboard pattern)

function DropdownMenu({ trigger, items }) {
    const [open, setOpen] = useState(false);
    const [activeIndex, setActiveIndex] = useState(-1);
    const itemRefs = useRef([]);

    const handleKeyDown = (e) => {
        switch (e.key) {
            case 'ArrowDown':
                e.preventDefault();
                setActiveIndex(i => Math.min(i + 1, items.length - 1));
                break;
            case 'ArrowUp':
                e.preventDefault();
                setActiveIndex(i => Math.max(i - 1, 0));
                break;
            case 'Escape':
                setOpen(false);
                triggerRef.current?.focus();
                break;
            case 'Home':
                setActiveIndex(0);
                break;
            case 'End':
                setActiveIndex(items.length - 1);
                break;
        }
    };

    useEffect(() => {
        if (activeIndex >= 0) {
            itemRefs.current[activeIndex]?.focus();
        }
    }, [activeIndex]);

    return (
        <div>
            <button
                aria-haspopup="listbox"
                aria-expanded={open}
                onClick={() => setOpen(!open)}
            >
                {trigger}
            </button>
            {open && (
                <ul role="listbox" onKeyDown={handleKeyDown}>
                    {items.map((item, i) => (
                        <li
                            key={item.id}
                            role="option"
                            tabIndex={-1}
                            ref={el => itemRefs.current[i] = el}
                        >
                            {item.label}
                        </li>
                    ))}
                </ul>
            )}
        </div>
    );
}

Focus Trap for Modal Windows

function Modal({ isOpen, onClose, children }) {
    const modalRef = useRef(null);

    useEffect(() => {
        if (!isOpen) return;

        const focusableSelectors = [
            'a[href]', 'button:not([disabled])', 'input:not([disabled])',
            'textarea', 'select', '[tabindex]:not([tabindex="-1"])'
        ].join(', ');

        const focusable = modalRef.current?.querySelectorAll(focusableSelectors);
        const first = focusable?.[0];
        const last = focusable?.[focusable.length - 1];

        first?.focus();

        const handleTab = (e) => {
            if (e.key !== 'Tab') return;

            if (e.shiftKey) {
                if (document.activeElement === first) {
                    e.preventDefault();
                    last?.focus();
                }
            } else {
                if (document.activeElement === last) {
                    e.preventDefault();
                    first?.focus();
                }
            }
        };

        const handleEsc = (e) => {
            if (e.key === 'Escape') onClose();
        };

        document.addEventListener('keydown', handleTab);
        document.addEventListener('keydown', handleEsc);

        return () => {
            document.removeEventListener('keydown', handleTab);
            document.removeEventListener('keydown', handleEsc);
        };
    }, [isOpen]);

    if (!isOpen) return null;

    return (
        <div role="dialog" aria-modal="true" ref={modalRef}>
            {children}
        </div>
    );
}

Testing

// Cypress — keyboard navigation testing
it('navigates menu with keyboard', () => {
    cy.get('[data-testid="nav-trigger"]').focus().type('{enter}');
    cy.get('[data-testid="nav-menu"]').should('be.visible');
    cy.focused().type('{downarrow}');
    cy.get('[data-testid="nav-item-0"]').should('be.focused');
    cy.focused().type('{esc}');
    cy.get('[data-testid="nav-trigger"]').should('be.focused');
});

Timeline

• Keyboard navigation audit: 1 day
• Fixing native elements and focus styles: 1–2 days
• Custom components (dropdowns, modals, sliders): 3–5 days