Skip to content

Keyboard Navigation#

TL;DR

Wunderbaum tree and treegrid is navigable using keyboard shortcuts. Different navigation modes are available.

The option keyboard: true enables standard keyboard navigation.

See also

See also a live demo and use the keyboard to navigate, expand, and edit grid cells.

General Keyboard Navigation#

We distinguish node states 'focused', 'active', and 'selected'.
setFocus() only sets a dotted border around the node. When autoActivate is enabled (which is on by default), the node also gets activated.
A node becomes 'selected', when the checkbox is checked.

A tree can have one of two navigation modes. We can toggle using the keyboard:

Row Mode ↔ Cell-Nav Mode

The initial mode, and if modes can be switched, is controlled by the navigationModeOption option:
If the tree has only one column, or if navigationModeOption is "row", Row Mode is obligatory. If the value is "cell", Cell-Nav Mode is obligatory.
A value of "startCell" or "startRow" allows switching.

In row mode, Wunderbaum behaves like a simple tree. Even if multiple columns are present, always the whole row is highlighted.

Windows macOS Function
AlphaNum Jump to next matching node, i.e. title starts with this character (if `quicksearch` is true).
Characters typed in quick succession extend the search term, including Space if a title matches (e.g. "lab c").
Tab, Shift + Tab Leave the Wunderbaum tree control and focus next/previous control on the page.
+ / - Expand/collapse node
Space Toggle selected status if checkbox option is on.
F2 Edit node title.
Enter If node is active and expandable: toggle expansion.
Note: Behaves as alias for F2 on macOS if edit.trigger option list contains "macEnter".
Escape Discard edit title operation if any.
Backspace Set focus to parent node.
ArrowLeft If expanded: collapse. Otherwise set focus to parent node.
ArrowRight If collapsed: expand.
Otherwise switch to →Cell-Nav Mode.
ArrowUp Set focus to previous sibling (or parent if already on first sibling).
ArrowDown Set focus to next visible node.
Ctrl + Arrow… ⌘ + Arrow… Same as plain Arrow…, but only sets the focus, even if autoActivate option is on.
Home Fn + ArrowLeft Select first row.
End Fn + ArrowRight Select last row.
PageUp Fn + ArrowUp Select top row in viewport or scroll one page upwards if we are already at the top.
PageDown Fn + ArrowDown Select bottom row in viewport or scroll one page down if we are already at the bottom.
Ctrl + Home,
Ctrl + End 		⌘ + ArrowUp,
⌘ + ArrowDown 		Select first / last row.

Cell-Nav mode is only available, when multiple columns are defined. In this mode we navigate the single grid cells in read-only mode mostly.
However, if the cell contains an embedded <input> element, we can focus that control and edit its content.

Windows macOS Function
+ / - Expand/collapse node if the title column is highlighted.
ArrowUp, ArrowDown, ArrowLeft, ArrowRight Navigate to adjacent cell.
ArrowLeft on the leftmost column switches to →Row Mode.
Tab, Shift + Tab Move to adjacent cell.
Escape If the focus is inside an embedded <input> element: discard changes and set focus to the outer cell.
Otherwise switch to →Row Mode.
F2 Edit the current grid cell. If the title column is highlighted, edit the node title.
Enter If on the first column and node is expandable: toggle expansion.
If the cell contains an embedded <input> element: set focus into that input control.
If the input control already had the focus, accept the entered data.
Note: Enter behaves as alias for F2 on macOS if the edit.trigger option list contains "macEnter".
AlphaNum If the cell contains an embedded <input> element: start editing its value.
Space Toggle value if current cell contains a checkbox. Toggle node selection if current cell is in the title column.
Home Fn + ArrowLeft Select leftmost cell.
End Fn + ArrowRight Select rightmost cell.
PageUp Fn + ArrowUp Select top cell in viewport or scroll one page upwards if we are already at the top.
PageDown Fn + ArrowDown Select bottom cell in viewport or scroll one page down if we are already at the bottom.
Ctrl + Home,
Ctrl + End 		⌘ + ArrowUp,
⌘ + ArrowDown 		Select top / bottom tree cell.

Accessibility#

Wunderbaum renders WAI-ARIA tree grid semantics, so screen readers can announce the tree structure:

  • The tree container has role="treegrid" and keeps the keyboard focus. Its aria-activedescendant attribute points to the focused row.
  • The header and the node list are role="rowgroup", with role="row" and role="columnheader" / role="gridcell" elements (aria-colindex, aria-sort for sortable columns).
  • Rows have aria-level, aria-setsize, aria-posinset, aria-expanded, aria-selected (if nodes can be selected), aria-busy (while loading), and aria-rowindex. Because rows are rendered on demand, the container has aria-rowcount with the number of all visible rows.
  • Decorative icons (indentation, expander, checkbox, column buttons) are aria-hidden.

Give the tree an accessible name, e.g. <div id="tree" aria-label="Project files"></div>.

Configuration and Customization#

const tree = new Wunderbaum({
  ...
  enable: true,
  autoActivate: true,
  checkbox: true,
  navigationModeOption: "startRow",  // | "cell" | "startCell" | "row"
  quicksearch: true,
  ...
  // --- Events ---
  keydown: (e) => {
    // Return false to prevent default behavior
  }
  ...
  edit: {
    trigger: ["F2", "macEnter", ...],
    ...
  },
});
  • tree.setNavigationOption(mode: NavModeEnum)
  • tree.setColumn(colIdx: number|string, options?: SetColumnOptions)
  • tree.setEnabled(flag: boolean)
div.wunderbaum.wb-grid.wb-cell-mode div.wb-row.wb-active span.wb-col.wb-active {
  /* Highlighted cell in cell-nav mode */
}

Code Hacks#