diff --git a/Keyboard-focus.md b/Keyboard-focus.md
index e9927b0..3149608 100644
--- a/Keyboard-focus.md
+++ b/Keyboard-focus.md
@@ -1,9 +1,43 @@
 [![Doc Status](https://godoc.org/github.com/mum4k/termdash/container?status.png)](https://godoc.org/github.com/mum4k/termdash/container)
 
-Containers track keyboard focus. By default, any keyboard events are only delivered to the widget in the focused container. The user changes the focused container by clicking on any area within the container. If the focused container has a border, its color will change according to the value of the [container.FocusedColor](https://godoc.org/github.com/mum4k/termdash/container#FocusedColor) option.
+## Overview
+
+Containers track keyboard focus. By default, any keyboard events are only delivered to the widget in the focused container. The user changes the focused container by using a mouse or delivering configured keyboard shortcuts. If the focused container has a border, its color will change according to the value of the [container.FocusedColor](https://godoc.org/github.com/mum4k/termdash/container#FocusedColor) option.
 
 Note that widgets can also register for global keyboard events, see the [[Widget API|widget-api]] for more details.
 
+## Focus indication
+
 The following diagram shows two containers, the right container has the keyboard focus so its border is highlighted. Refer to [[Container style|container-style]] for details about border styles and options that customize the colors.
 
-[[/images/container-api/border_styles.png|border_styles]]
\ No newline at end of file
+[[/images/container-api/border_styles.png|border_styles]]
+
+## Changing which container is focused
+
+### Using mouse events
+
+A mouse click delivered to an area within a container moves the keyboard focus to that container.
+
+### Using keyboard events
+
+The container offers two options that allow the user to configure keyboard keys that change which container is focused. Using these keys, the user can change the focus to the next or the previous container. The containers are organised in a [[binary tree|binary-tree-layout]].
+
+When changing focus to the **next** container, the focus will move to the next leaf container (a container that isn't itself split into sub-containers) that comes right after the currently focused container in a DFS (Depth-first search) traversal of the binary tree.
+
+Similarly when changing focus to the **previous** container, the focus will move to the previous leaf container in that comes right before the currently focused container in a DFS (Depth-first search) traversal of the binary tree.
+
+Note that this ordering applies regardless whether the application uses the [[Binary tree layout|binary-tree-layout]] or the [[Grid layout|grid-layout]]. Containers are always represented as a binary tree within `termdash`.
+
+#### [container.KeyFocusNext](https://godoc.org/github.com/mum4k/termdash/container#KeyFocusNext):
+
+The **container.KeyFocusNext** option is used to configure a key that will move the focus to the next container. No key will perform this function if not specified.
+
+#### [container.KeyFocusPrevious](https://godoc.org/github.com/mum4k/termdash/container#KeyFocusPrevious):
+
+The **container.KeyFocusPrevious** option is used to configure a key that will move the focus to the previous container. No key will perform this function if not specified.
+
+#### Delivering keyboard keys to widgets
+
+Even if a key is configured to move the focus, it still gets delivered as a keyboard event to widgets that subscribe to keyboard events. See the [[Widget API|Widget-API]] for details about subscribing widgets to keyboard events.
+
+A widget that subscribed with **KeyScopeGlobal** always get's the key press event. A widget that subscribed with **KeyScopeFocused** only gets the key press event if it was focused before the focus change.
\ No newline at end of file