From 06cf2b9c5cfa285e8a5bfe72a236289f9af1e966 Mon Sep 17 00:00:00 2001
From: devchangjun <ckdwns9121@naver.com>
Date: Mon, 13 Jul 2026 00:19:28 +0900
Subject: [PATCH] Clarify column visibility toggle labels

Column visibility menus render column objects, not active header objects, so rendering columnDef.header directly can fail or confuse users when headers are JSX/templates or when columns are hidden. The guide now shows a stable label map fallback and calls out flexRender as the correct path for real header rendering.

Related: TanStack/table#5751
Confidence: high
Scope-risk: narrow
Tested: pnpm prettier --write docs/framework/react/guide/column-visibility.md; pnpm test:docs
Not-tested: Full repository test suite
---
 docs/framework/react/guide/column-visibility.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/framework/react/guide/column-visibility.md b/docs/framework/react/guide/column-visibility.md
index 9addb144b9..b11d4c9d23 100644
--- a/docs/framework/react/guide/column-visibility.md
+++ b/docs/framework/react/guide/column-visibility.md
@@ -139,6 +139,11 @@ There are several column API methods that are useful for rendering column visibi
 - `column.getToggleVisibilityHandler` - Shortcut for hooking up the `column.toggleVisibility` method to a UI event handler.
 
 ```tsx
+const columnLabels: Record<string, string> = {
+  firstName: 'First Name',
+  lastName: 'Last Name',
+}
+
 {
   table.getAllColumns().map((column) => (
     <label key={column.id}>
@@ -148,12 +153,21 @@ There are several column API methods that are useful for rendering column visibi
         onChange={column.getToggleVisibilityHandler()}
         type="checkbox"
       />
-      {column.columnDef.header}
+      {columnLabels[column.id] ?? column.id}
     </label>
   ))
 }
 ```
 
+> **Note**: `column.columnDef.header` is a header render template. It can be a
+> string, JSX, or a function that needs a header context and should be rendered
+> with `flexRender` when you are rendering actual table headers. A column
+> visibility menu is usually rendering columns rather than header objects, and a
+> hidden column may not have an active header context. For visibility toggles,
+> prefer a stable text label such as a custom map of labels keyed by column ID,
+> typed `columnDef.meta` (for example `column.columnDef.meta.label`), or
+> `column.id`.
+
 ### Column Visibility Aware Table APIs
 
 When you render your header, body, and footer cells, there are a lot of API options available. You may see APIs like `table.getAllLeafColumns` and `row.getAllCells`, but if you use these APIs, they will not take column visibility into account. Instead, you need to use the "visible" variants of these APIs, such as `table.getVisibleLeafColumns` and `row.getVisibleCells`.