Keyboard Navigation – contenteditable.lab

Overview

Keyboard navigation in contenteditable elements is complex and varies significantly across browsers, operating systems, and input methods. This guide covers all aspects of keyboard navigation, from basic arrow key movement to complex scenarios involving IME composition and non-editable regions.

⚠️ Browser & Platform Differences

Keyboard navigation behavior varies by:

Browser (Chrome, Firefox, Safari, Edge)
Operating system (macOS, Windows, Linux, iOS, Android)
Input method (IME composition, mobile keyboards)
Keyboard layout (QWERTY, Dvorak, etc.)
Content structure (nested elements, contenteditable="false")

Arrow Keys

Basic Arrow Key Movement

Arrow Key Behavior

Arrow keys move the cursor one character or line at a time:

ArrowLeft (←): Move cursor one character to the left
ArrowRight (→): Move cursor one character to the right
ArrowUp (↑): Move cursor up one line, maintaining horizontal position
ArrowDown (↓): Move cursor down one line, maintaining horizontal position

⚠️ Character vs. Visual Position

Problem: Arrow keys move by character position, not visual position. This can cause issues with:

Emoji: Arrow keys may skip over entire emoji clusters instead of moving by visual position
Combining characters: Complex Unicode sequences may be skipped
RTL text: Right-to-left text may behave unexpectedly

<!-- Example: Emoji skipping -->
<div contenteditable="true">
  Hello 👋 World 🌍
</div>

<!-- Cursor at: H|ello 👋 World -->
<!-- Press ArrowRight → May jump to: Hello 👋| World -->
<!-- Skips the entire emoji cluster instead of moving character by character -->

<!-- ✅ GOOD: Handle emoji clusters manually if needed -->
element.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
    const selection = window.getSelection();
    if (selection.rangeCount === 0) return;
    
    const range = selection.getRangeAt(0);
    const text = range.startContainer.textContent;
    const offset = range.startOffset;
    
    // Check if we're at a grapheme cluster boundary
    // Use Intl.Segmenter or similar to handle properly
    if (e.key === 'ArrowRight' && offset < text.length) {
      const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
      const segments = Array.from(segmenter.segment(text));
      // Find next grapheme boundary
      // Move cursor accordingly
    }
  }
});

Modifier Keys with Arrow Keys

Common Modifier Combinations

Key Combination	macOS	Windows/Linux	Behavior
`Ctrl/Cmd + ←`	Word left	Word left	Move to start of word
`Ctrl/Cmd + →`	Word right	Word right	Move to end of word
`Ctrl/Cmd + ↑`	Line start	Paragraph start	Move to start of line/paragraph
`Ctrl/Cmd + ↓`	Line end	Paragraph end	Move to end of line/paragraph
`Shift + ←/→`	Extend selection	Extend selection	Extend selection character by character
`Shift + Ctrl/Cmd + ←/→`	Extend by word	Extend by word	Extend selection word by word
`Alt + ←/→`	Word left/right	Word left/right	Move by word (alternative)

⚠️ Browser Differences in Word Movement

Problem: Word boundary detection varies across browsers:

Chrome: May move by word even without modifier keys in some cases
Firefox: More consistent word boundary detection
Safari: Uses different word boundary rules (may include punctuation differently)
Unicode: Word boundaries for non-ASCII characters may be inconsistent

Arrow Keys with contenteditable="false"

⚠️ Navigation Issues with Non-Editable Content

Problem: When navigating with arrow keys near or within contenteditable="false" elements:

Arrow keys may skip over non-editable content entirely
Cursor may appear inside non-editable elements where it shouldn't be
Navigation may be blocked or jump to unexpected locations
Behavior varies significantly between browsers

See contenteditable="false" documentation for detailed information and workarounds.

Special Navigation Keys

Home and End Keys

Home/End Key Behavior

Home: Move cursor to start of current line
End: Move cursor to end of current line
Ctrl/Cmd + Home: Move cursor to start of document
Ctrl/Cmd + End: Move cursor to end of document
Shift + Home/End: Extend selection to start/end of line
Shift + Ctrl/Cmd + Home/End: Extend selection to start/end of document

⚠️ Line vs. Paragraph

Browser differences: The definition of "line" varies:

Chrome/Firefox: Home/End move to start/end of the current visual line (may wrap)
Safari: May move to start/end of paragraph instead of visual line
Word wrapping: Behavior may differ when text wraps to multiple lines

Page Up and Page Down

Page Up/Down Behavior

PageUp: Move cursor up by one viewport height
PageDown: Move cursor down by one viewport height
Shift + PageUp/PageDown: Extend selection by one viewport
Ctrl/Cmd + PageUp/PageDown: May scroll without moving cursor (browser-dependent)

⚠️ Viewport Calculation

Problem: Page Up/Down behavior depends on viewport size and scroll position, which can be unpredictable in contenteditable elements with dynamic content.

Tab Navigation

⚠️ Tab Key Behavior

Problem: The Tab key has special meaning in contenteditable:

Default behavior: Tab key inserts a tab character (or spaces) instead of moving focus
Focus management: Tab key does not move focus to next focusable element by default
tabindex: Using tabindex may not work consistently across browsers

<!-- ❌ BAD: Tab inserts character instead of moving focus -->
<div contenteditable="true">
  <!-- Press Tab → Inserts tab character, doesn't move focus -->
</div>

<!-- ✅ GOOD: Intercept Tab key for focus management -->
element.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    e.preventDefault();
    
    if (e.shiftKey) {
      // Shift+Tab: Move to previous focusable element
      moveFocusToPrevious();
    } else {
      // Tab: Move to next focusable element
      moveFocusToNext();
    }
  }
});

// Or allow Tab to insert character in some cases
element.addEventListener('keydown', (e) => {
  if (e.key === 'Tab' && !e.shiftKey) {
    // Check if we want to insert tab or move focus
    if (shouldInsertTab()) {
      // Insert tab character
      e.preventDefault();
      document.execCommand('insertText', false, '	');
    } else {
      // Move focus
      e.preventDefault();
      moveFocusToNext();
    }
  }
});

Tab Navigation Best Practices

Intercept Tab: Always intercept Tab key if you want focus management
User preference: Consider allowing users to choose between inserting tab or moving focus
Context-aware: Insert tab when editing, move focus when navigating between editors
Accessibility: Ensure Tab navigation works for screen reader users

IME Composition & Keyboard Navigation

⚠️ Arrow Keys During Composition

Problem: During IME composition, arrow key behavior changes:

Arrow keys may cancel the active composition
Arrow keys may commit composition text prematurely
Navigation may be blocked until composition completes
Behavior varies by IME and platform (Korean, Japanese, Chinese IMEs behave differently)

// Example: Handle arrow keys during composition
let isComposing = false;

element.addEventListener('compositionstart', () => {
  isComposing = true;
});

element.addEventListener('compositionend', () => {
  isComposing = false;
});

element.addEventListener('keydown', (e) => {
  if (isComposing && ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(e.key)) {
    // Option 1: Prevent arrow keys during composition
    e.preventDefault();
    // Option 2: Allow but handle composition cancellation
    // The composition may be cancelled by the browser
  }
});

IME-Specific Behavior

Korean IME

Arrow keys may cancel composition
Left/Right arrows may move within composition text (browser-dependent)
Up/Down arrows typically cancel composition

Japanese IME

Arrow keys may navigate candidate list
Left/Right may move within composition
Up/Down may select candidates

Chinese IME

Similar to Japanese IME
Arrow keys may interact with candidate selection

Mobile Keyboard Navigation

Mobile-Specific Behavior

On mobile devices, keyboard navigation works differently:

Virtual keyboards: Arrow keys may not be available on all virtual keyboards
Touch selection: Users primarily use touch for selection, not keyboard
External keyboards: When external keyboard is connected, behavior may differ from desktop
iOS: Arrow keys on external keyboard may behave differently than on macOS
Android: Keyboard behavior varies by manufacturer and keyboard app

⚠️ Mobile Arrow Key Support

Problem: Arrow keys may not be available or may behave unexpectedly on mobile:

Many virtual keyboards don't include arrow keys
External keyboards may have limited arrow key support
Touch selection handles may interfere with keyboard navigation
Virtual keyboard may close when arrow keys are pressed

Browser-Specific Differences

Chrome/Edge

Arrow keys may move by word instead of character in some cases (Windows)
Word boundary detection may include punctuation differently
Home/End may move to visual line start/end
Tab key inserts tab character by default

Firefox

Generally more consistent arrow key behavior
Better word boundary detection
Home/End behavior is more predictable
Tab key behavior similar to Chrome

Safari

Arrow keys may behave differently, especially with modifier keys
Home/End may move to paragraph start/end instead of line
Cmd+Arrow behavior differs from Ctrl+Arrow on Windows
Tab key may have different default behavior

Best Practices

Implementing Custom Keyboard Navigation

Intercept keydown: Use keydown event, not keypress or keyup
Check modifiers: Always check ctrlKey, metaKey, shiftKey, altKey
Handle composition: Check for active IME composition before handling navigation
Test across browsers: Keyboard behavior varies significantly - test in all major browsers
Respect platform conventions: Use Cmd on macOS, Ctrl on Windows/Linux
Provide fallbacks: Don't break default behavior unless necessary

// Example: Comprehensive keyboard navigation handler
element.addEventListener('keydown', (e) => {
  // Check for active composition
  if (isComposing) {
    // Handle composition-specific navigation
    handleCompositionNavigation(e);
    return;
  }
  
  // Handle arrow keys
  if (['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(e.key)) {
    const selection = window.getSelection();
    if (selection.rangeCount === 0) return;
    
    const range = selection.getRangeAt(0);
    
    // Check for contenteditable="false" issues
    if (isInContentEditableFalse(range.startContainer)) {
      e.preventDefault();
      handleNavigationInNonEditable(e.key, range);
      return;
    }
    
    // Handle modifier keys
    if (e.ctrlKey || e.metaKey) {
      e.preventDefault();
      handleWordNavigation(e.key, e.shiftKey, range);
      return;
    }
    
    if (e.shiftKey) {
      // Extend selection
      // Allow default behavior or handle manually
      return;
    }
    
    // Default arrow key behavior
    // Allow browser to handle or customize
  }
  
  // Handle Home/End
  if (e.key === 'Home' || e.key === 'End') {
    if (e.ctrlKey || e.metaKey) {
      e.preventDefault();
      handleDocumentNavigation(e.key, e.shiftKey);
      return;
    }
    // Default Home/End behavior
  }
  
  // Handle Tab
  if (e.key === 'Tab') {
    e.preventDefault();
    if (e.shiftKey) {
      moveFocusToPrevious();
    } else {
      moveFocusToNext();
    }
  }
});