diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua
index 9ef13ffd9..94cc3bd15 100644
--- a/lib/wibox/layout/grid.lua
+++ b/lib/wibox/layout/grid.lua
@@ -7,8 +7,15 @@
 --
 --@DOC_wibox_layout_grid_imperative_EXAMPLE@
 --
--- Using the declarative system, widgets are automatically added next to each
--- other spanning only one cell.
+-- The same can be done using the declarative syntax. When using this mode,
+-- all widgets will again the `row_span` and `col_span` properties:
+--
+--@DOC_wibox_layout_grid_declarative1_EXAMPLE@
+--
+-- When `col_index` and `row_index` are not provided, the widgets are
+-- automatically added next to each other spanning only one cell:
+--
+--@DOC_wibox_layout_grid_declarative2_EXAMPLE@
 --
 --@DOC_wibox_layout_defaults_grid_EXAMPLE@
 -- @author getzze
@@ -314,6 +321,9 @@ end
 --
 -- The widgets are assumed to span one cell.
 --
+-- If the widgets have a `row_index`, `col_index`, `col_span`
+-- or `row_span` property, it will be honorred.
+--
 -- @method add
 -- @tparam wibox.widget ... Widgets that should be added (must at least be one)
 -- @interface layout
@@ -323,9 +333,16 @@ function grid:add(...)
     assert(args.n > 0, "need at least one widget to add")
     local row, column
     for i=1, args.n do
+        local w = args[i]
         -- Get the next empty coordinate to insert the widget
         row, column = self:get_next_empty(row, column)
-        self:add_widget_at(args[i], row, column, 1, 1)
+        self:add_widget_at(
+            w,
+            w.row_index or row,
+            w.col_index or column,
+            w.row_span or 1,
+            w.col_span or 1
+        )
     end
 end
 
diff --git a/tests/examples/wibox/layout/grid/declarative1.lua b/tests/examples/wibox/layout/grid/declarative1.lua
new file mode 100644
index 000000000..0d5a5c4cc
--- /dev/null
+++ b/tests/examples/wibox/layout/grid/declarative1.lua
@@ -0,0 +1,61 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START
+local generic_widget = ... --DOC_NO_USAGE
+local wibox     = require("wibox")
+
+--DOC_HIDE_END
+
+   local lorem  = "Lorem ipsum dolor sit amet, consectetur adipiscing " ..
+       "elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
+
+--DOC_NEWLINE
+
+   local l = wibox.widget {
+       {
+           text      = lorem,
+           row_index = 1,
+           col_index = 1,
+           col_span  = 3,
+           widget    = generic_widget
+       },
+       {
+           text      = "first",
+           col_span = 2,
+           row_index = 2,
+           col_index = 1,
+           widget    = generic_widget
+       },
+       {
+           text      = "third",
+           row_index = 2,
+           col_index = 3,
+           row_span  = 2,
+           widget    = generic_widget
+       },
+       {
+           text      = "second",
+           row_index = 3,
+           col_index = 1,
+           col_span  = 2,
+           widget    = generic_widget
+       },
+       {
+           text      = "fourth",
+           row_index = 4,
+           col_index = 1,
+           widget    = generic_widget
+       },
+       {
+           text      = "fifth",
+           row_index = 4,
+           col_index = 2,
+           col_span  = 2,
+           widget    = generic_widget
+       },
+       homogeneous     = true,
+       spacing         = 5,
+       min_cols_size   = 10,
+       min_rows_size   = 10,
+       layout          = wibox.layout.grid,
+   }
+
+return l, l:fit({dpi=96}, 300, 200) --DOC_HIDE
diff --git a/tests/examples/wibox/layout/grid/declarative2.lua b/tests/examples/wibox/layout/grid/declarative2.lua
new file mode 100644
index 000000000..4e9a11dea
--- /dev/null
+++ b/tests/examples/wibox/layout/grid/declarative2.lua
@@ -0,0 +1,18 @@
+--DOC_GEN_IMAGE  --DOC_HIDE
+local generic_widget = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+
+    local l = wibox.widget {
+        generic_widget("first"),
+        generic_widget("second"),
+        generic_widget("third"),
+        generic_widget("fourth"),
+        generic_widget("fifth"),
+        forced_num_cols = 2,
+        spacing         = 5,
+        min_cols_size   = 10,
+        min_rows_size   = 10,
+        layout          = wibox.layout.grid,
+    }
+
+return l, l:fit({dpi=96}, 300, 200) --DOC_HIDE