diff --git a/content/blocks/list.md b/content/blocks/list.md
index b9c5c5f..2b307f3 100644
--- a/content/blocks/list.md
+++ b/content/blocks/list.md
@@ -111,6 +111,44 @@ Define the hook partial in your site's `layouts/_partials` folder. The following
 
 {{< file file="./layouts/_partials/assets/table-filter-hook.html" full=false lang="go-template" >}}
 
+Set `filter_responsive` to replace the button group with a dropdown below the site's main breakpoint. A group of more than a few categories is wider than a phone, and the button group does not wrap. The dropdown and the button group stay in step, so moving across the breakpoint never changes which category is selected. It defaults to `false`, so a list keeps its button group at every width unless you ask otherwise.
+
+### Responsive Tables
+
+A table with several columns runs off the side of a small screen. Set `wrap` to move a record's last column onto a row of its own below the site's main breakpoint, which is usually enough when one column holds most of the width — a description, say.
+
+Set `wrap_cols` when it is not. It takes a column count per rendered row, so a record folds into groups and stacks as a card. `"1,2"` across the three-column hook below keeps the article on the lead row and folds the category and published date onto a row beneath it.
+
+Only the first group keeps one cell per column, so it alone stays aligned down the table; every later group lays its values out in equal columns that reduce in number to fit the viewport. The counts must be positive and add up to the number of columns your hook renders — a list that does not, such as one left behind when a column was added, is refused and the table falls back to wrapping the last column only.
+
+Folded columns hide their headings, so their values appear without labels. That suits self-describing content such as badges, which is why the grouping is yours to choose rather than derived.
+
+<!-- markdownlint-disable MD037 -->
+{{< example-bookshop lang="bookshop" >}}
+
+```yml
+- _bookshop_name: list
+  heading:
+    title: Recent articles
+    align: start
+  input:
+    section: blog
+    reverse: false
+    sort: date
+  hide_empty: false
+  hook: assets/table-filter-hook
+  wrap: true
+  wrap_cols: "1,2"
+  sortable: true
+  background:
+    color: body-tertiary
+    subtle: false
+  justify: start
+```
+
+{{< /example-bookshop >}}
+<!-- markdownlint-enable MD037 -->
+
 ### Custom List
 
 Customize the list by providing a `hook` partial.