diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua
index f13278a93..ac12f58b2 100644
--- a/lib/gears/shape.lua
+++ b/lib/gears/shape.lua
@@ -43,9 +43,46 @@
 local g_matrix = require( "gears.matrix" )
 local unpack   = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
 local atan2    = math.atan2 or math.atan -- lua 5.3 compat
+local min      = math.min
+local cos      = math.cos
+local sin      = math.sin
 
 local module = {}
 
+--- Add a star shape to the current path.
+-- The star size will be the minimum of the given width and weight
+--
+-- @DOC_gears_shape_star_EXAMPLE@
+--
+-- @param cr A cairo context
+-- @tparam number width The width constraint
+-- @tparam number height The height constraint
+-- @tparam number n Number of grams (default n = 5 -> pentagram)
+-- @staticfct gears.shape.star
+function module.star(cr, width, height, n)
+    -- use the minimum as size
+    local s = min(width, height) / 2
+
+    -- draw pentagram by default
+    n = n or 5
+    local a = 2 * math.pi / n
+
+    -- place the star at the center
+    cr:save()
+    cr:translate(width/2, height/2)
+    cr:rotate(-math.pi/2)
+
+    for i = 0,(n - 1) do
+        cr:line_to(s   * cos((i      ) * a), s   * sin((i      ) * a))
+        cr:line_to(s/2 * cos((i + 0.5) * a), s/2 * sin((i + 0.5) * a))
+    end
+
+    -- restore the context
+    cr:restore()
+
+    cr:close_path()
+end
+
 --- Add a rounded rectangle to the current path.
 -- Note: If the radius is bigger than either half side, it will be reduced.
 --
diff --git a/tests/examples/gears/shape/star.lua b/tests/examples/gears/shape/star.lua
new file mode 100644
index 000000000..5aa76731f
--- /dev/null
+++ b/tests/examples/gears/shape/star.lua
@@ -0,0 +1,15 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local shape,cr,show = ... --DOC_HIDE
+
+shape.star(cr, 70, 70, 4)
+show(cr) --DOC_HIDE
+
+shape.star(cr, 70, 70, 9)
+show(cr) --DOC_HIDE
+
+shape.transform(shape.star) : translate(70/2, 70/2)
+: rotate(math.pi) : scale(0.5, 0.75)
+: translate(-70/2, -70/2) (cr, 70, 70)
+show(cr) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80