diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua
index 285bc8c013..2e7bdb837e 100644
--- a/lib/awful/wallpaper.lua
+++ b/lib/awful/wallpaper.lua
@@ -30,6 +30,11 @@
 --
 --@DOC_awful_wallpaper_mazimized3_EXAMPLE@
 --
+-- To maintain the image's aspect ratio while filling the
+-- screen, the image can be cropped using `gears.surface`:
+--
+--@DOC_awful_wallpaper_mazimized4_EXAMPLE@
+--
 -- Finally, it is also possible to use simpler "branding" in a corner using
 -- `awful.placement`:
 --
diff --git a/tests/examples/awful/wallpaper/mazimized4.lua b/tests/examples/awful/wallpaper/mazimized4.lua
new file mode 100644
index 0000000000..7dff60973a
--- /dev/null
+++ b/tests/examples/awful/wallpaper/mazimized4.lua
@@ -0,0 +1,22 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE
+local awful =  { wallpaper = require("awful.wallpaper") } --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+screen[1]._resize {x = 0, y = 0, width = 320, height = 196} --DOC_HIDE
+local s = screen[1] --DOC_HIDE
+
+   awful.wallpaper {
+       screen = s,
+       widget = {
+            image  = gears.surface.crop_surface {
+                surface = gears.surface.load_uncached(beautiful.wallpaper),
+                ratio = s.geometry.width/s.geometry.height,
+            },
+            widget = wibox.widget.imagebox,
+        },
+   }
+
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+