From fdb2b69823205f9c23796ba5a1c8ce6439c6d736 Mon Sep 17 00:00:00 2001
From: 81reap <prayag.bhakar@gmail.com>
Date: Wed, 28 Oct 2026 17:29:30 -0400
Subject: [PATCH] feat(table) :: add top level `title`

Now the table component accepts a top-level `title`, shown in a header above the table like in the list and datagrid components.

Fixes #1261

Assisted By :: Claude Opus 5.5
---
 CHANGELOG.md                                                 | 2 ++
 .../official-site/sqlpage/migrations/01_documentation.sql    | 1 +
 sqlpage/templates/table.handlebars                           | 5 +++++
 .../sql_test_files/component_rendering/table_title_1261.sql  | 2 ++
 4 files changed, 10 insertions(+)
 create mode 100644 tests/sql_test_files/component_rendering/table_title_1261.sql

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e44475223..b47789aa4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 - Refined the official website with muted blue accents, simpler navigation, a clearer primary action, and a level SQL ribbon with vertical separators, and a grounded studio scene with brushed metal and physical reflections. Restored visible progress in the streaming comparison animation.
 
+- The table component accepts a top-level `title`, shown in a header above the table like in the list and datagrid components. ([#1261](https://github.com/sqlpage/SQLPage/issues/1261))
+
 - Restored parameter reuse for repeated variables on SQL Server, PostgreSQL, and SQLite, fixing SQL Server and PostgreSQL queries that repeat a variable-dependent expression in `SELECT` and `GROUP BY`.
 
 ## v0.47.0 (2026-10-15)
diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql
index 7766adbbf..df638dd40 100644
--- a/examples/official-site/sqlpage/migrations/01_documentation.sql
+++ b/examples/official-site/sqlpage/migrations/01_documentation.sql
@@ -951,6 +951,7 @@ Advanced users can apply custom styles to table columns using a CSS class with t
 
 INSERT INTO parameter(component, name, description, type, top_level, optional) SELECT 'table', * FROM (VALUES
     -- top level
+    ('title', 'A title displayed above the table.', 'TEXT', TRUE, TRUE),
     ('sort', 'Make the columns clickable to let the user sort by the value contained in the column.', 'BOOLEAN', TRUE, TRUE),
     ('search', 'Add a search bar at the top of the table, letting users easily filter table rows by value.', 'BOOLEAN', TRUE, TRUE),
     ('initial_search_value', 'Pre-fills the search bar used to filter the table. The user will still be able to edit the value to display table rows that will initially be filtered out.', 'TEXT', TRUE, TRUE),
diff --git a/sqlpage/templates/table.handlebars b/sqlpage/templates/table.handlebars
index a40c6b1e7..b368b20f4 100644
--- a/sqlpage/templates/table.handlebars
+++ b/sqlpage/templates/table.handlebars
@@ -1,4 +1,9 @@
 <div class="card my-2 {{class}}" {{#if overflow}}style="width: fit-content;"{{/if}} {{#if id}}id="{{id}}"{{/if}}>
+    {{#if title}}
+        <div class="card-header">
+            <h2 class="card-title">{{title}}</h2>
+        </div>
+    {{/if}}
     <div class="card-body p-0" data-pre-init="table">
         {{#if (or search initial_search_value)}}
         <div class="p-3">
diff --git a/tests/sql_test_files/component_rendering/table_title_1261.sql b/tests/sql_test_files/component_rendering/table_title_1261.sql
new file mode 100644
index 000000000..5f2f8ed63
--- /dev/null
+++ b/tests/sql_test_files/component_rendering/table_title_1261.sql
@@ -0,0 +1,2 @@
+select 'table' as component, 'It works !' as title;
+select 1 as x;