Keyboard navigation

How focus looks and moves in Koala: one quiet focus ring, a predictable tab order and the same keys everywhere.

The focus ring#

Every control shows the same ring when it takes focus from the keyboard: 2px of a soft grey, --focus, drawn 2px away from the control. It is quiet on purpose. It tells you where you are without competing with the primary action, and it still clears 3:1 against the ground in all four themes.

Press Tab inside the preview to walk through it.

Only from the keyboard#

The ring answers :focus-visible, not :focus. A click never leaves a ring behind; Tab, the arrows and a screen reader always do. Fields are the one exception: a focused field shows its edge for mouse and keyboard alike, because typing needs to know where the caret is.

Offset or inset#

A control that stands on its own, a Button, a Card, a Switch, draws the ring 2px outside its edge. A control that hugs the edge of its container, a tab inside its track or a row inside a list, draws it inset, so nothing around it has to make room and no container can cut it off.

Quarterly report
Revenue, churn and the accounts to watch.
One command adds it.

Scrollers never cut a ring#

A region that scrolls takes focus too, so the arrows can scroll it. Its ring is drawn inset, and scrolling containers carry a little scroll padding, so a focused child lands short of the edge instead of under it.

export const theme = createTheme({ accent: "orange", radius: "md", density: "comfortable", scrollbar: "native", motion: "default" })

One tab stop per group#

Tab moves between groups, the arrows move inside one. A Tabs list, a Toggle Group, a menu or a list of rows is a single stop: Tab enters on the selected item and leaves in one press. The order follows the reading order of the page, so never set a positive tabIndex. The hook behind it is useRovingFocus, documented in Behaviors.

Keys by pattern#

The same pattern answers the same keys in every component that uses it.

PatternKeysWhat they do
Button, Switch, CheckboxSpaceEnterPress. Space toggles a Switch or Checkbox.
Tabs, Segmented, Toggle Group←→HomeEndMove between items. One tab stop for the group.
Menu, Dropdown, Context Menu↑↓→EscMove, open a submenu, close and return to the trigger.
Select, Combobox, Command↑↓EnterEscMove the highlight while focus stays in the input, pick, close.
List, Tree↑↓←→Move between rows. In a Tree, collapse and expand.
Dialog, Sheet, DrawerTabEscFocus stays inside while open. Esc closes and returns focus.
Data Grid, Calendar↑↓←→HomeEndMove cell by cell, jump to the row or week ends.
Slider←→PageUpPageDownStep the value, or step it by ten.

Focus comes back#

Opening a Dialog, Sheet, Popover or menu moves focus inside it. Closing it, with Esc, a button or a click outside, returns focus to the control that opened it, so the next Tab carries on from where you were.

Your own components#

Use ring-focus for any focus ring you draw, never ring-brand or the neutral ring-ring. On a photo or a coloured band where grey cannot read, take that surface’s ink instead, white on media or the background on an inverse band.

tile.tsxTSX
const tile = tv({  base: [    "rounded-xl bg-card ring-1 ring-edge",    "outline-none focus-visible:ring-2 focus-visible:ring-focus",    "focus-visible:ring-offset-2 focus-visible:ring-offset-background",  ],})