diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua
index 3dc5201df..d5f3881f1 100644
--- a/lib/awful/prompt.lua
+++ b/lib/awful/prompt.lua
@@ -72,6 +72,16 @@
 --
 -- @DOC_wibox_awidget_prompt_vilike_EXAMPLE@
 --
+-- *[Example three] Key listener*:
+--
+-- The 2 previous examples were focused on changing the prompt behavior. This
+-- one explains how to "spy" on the prompt events. This can be used for
+--
+-- * Implementing more complex mutator
+-- * Synchronising other widgets
+-- * Showing extra tips to the user
+--
+-- @DOC_wibox_awidget_prompt_keypress_EXAMPLE@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
diff --git a/tests/examples/wibox/awidget/prompt/keypress.lua b/tests/examples/wibox/awidget/prompt/keypress.lua
new file mode 100644
index 000000000..a7a541ac8
--- /dev/null
+++ b/tests/examples/wibox/awidget/prompt/keypress.lua
@@ -0,0 +1,33 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt"),--DOC_HIDE
+                    util   = require("awful.util"),--DOC_HIDE
+                    screen = require("awful.screen")}--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+local naughty   = {} --DOC_HIDE
+
+    local atextbox = wibox.widget.textbox()
+
+    local notif = nil
+    awful.prompt.run {
+        prompt               = "<b>Run: </b>",
+        keypressed_callback  = function(mod, key, cmd) --luacheck: no unused args
+            if key == "Shift_L" then
+                notif = naughty.notify { text = "Shift pressed" }
+            end
+        end,
+        keyreleased_callback = function(mod, key, cmd) --luacheck: no unused args
+            if notif then
+                naughty.destroy(notif)
+                notif = nil
+            end
+        end,
+        textbox              = atextbox,
+        history_path         = awful.util.getdir("cache") .. "/history",
+    }
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE