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.
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.
| Pattern | Keys | What they do |
|---|---|---|
| Button, Switch, Checkbox | SpaceEnter | Press. Space toggles a Switch or Checkbox. |
| Tabs, Segmented, Toggle Group | ←→HomeEnd | Move between items. One tab stop for the group. |
| Menu, Dropdown, Context Menu | ↑↓→Esc | Move, open a submenu, close and return to the trigger. |
| Select, Combobox, Command | ↑↓EnterEsc | Move the highlight while focus stays in the input, pick, close. |
| List, Tree | ↑↓←→ | Move between rows. In a Tree, collapse and expand. |
| Dialog, Sheet, Drawer | TabEsc | Focus stays inside while open. Esc closes and returns focus. |
| Data Grid, Calendar | ↑↓←→HomeEnd | Move cell by cell, jump to the row or week ends. |
| Slider | ←→PageUpPageDown | Step 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.
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",
],
})