0
# Tiptap Extension Table Header
1

2
The @tiptap/extension-table-header package provides table header cell functionality for Tiptap rich text editors. It exports the TableHeader node extension and its configuration options from the core @tiptap/extension-table package.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-table-header
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-table-header`
10

11
## Core Imports
12

13
```typescript
14
import TableHeader from "@tiptap/extension-table-header";
15
import { TableHeader, TableHeaderOptions } from "@tiptap/extension-table-header";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const TableHeader = require("@tiptap/extension-table-header");
22
const { TableHeader, TableHeaderOptions } = require("@tiptap/extension-table-header");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { Editor } from "@tiptap/core";
29
import TableHeader from "@tiptap/extension-table-header";
30

31
const editor = new Editor({
32
  extensions: [
33
    TableHeader.configure({
34
      HTMLAttributes: {
35
        class: 'custom-table-header',
36
      },
37
    }),
38
  ],
39
});
40
```
41

42
## Capabilities
43

44
### Table Header Node Extension
45

46
Creates table header cells (th elements) in Tiptap tables with support for spanning columns and rows.
47

48
```typescript { .api }
49
/**
50
 * Tiptap Node extension for creating table header cells
51
 */
52
const TableHeader: Node<TableHeaderOptions>;
53

54
interface TableHeaderOptions {
55
  /**
56
   * The HTML attributes for a table header node.
57
   * @default {}
58
   * @example { class: 'foo' }
59
   */
60
  HTMLAttributes: Record<string, any>;
61
}
62
```
63

64
**Usage Example:**
65

66
```typescript
67
import { Editor } from "@tiptap/core";
68
import TableHeader from "@tiptap/extension-table-header";
69

70
// Basic configuration
71
const editor = new Editor({
72
  extensions: [
73
    TableHeader,
74
  ],
75
});
76

77
// With custom HTML attributes
78
const editorWithCustomAttributes = new Editor({
79
  extensions: [
80
    TableHeader.configure({
81
      HTMLAttributes: {
82
        class: 'my-table-header',
83
        style: 'font-weight: bold;',
84
      },
85
    }),
86
  ],
87
});
88
```
89

90
### Node Properties
91

92
The TableHeader extension defines a node with the following characteristics:
93

94
```typescript { .api }
95
interface TableHeaderNode {
96
  /** Node name identifier */
97
  name: 'tableHeader';
98
  /** Content model allowing block-level content */
99
  content: 'block+';
100
  /** Table role for ProseMirror table functionality */
101
  tableRole: 'header_cell';
102
  /** Prevents content from being selected across node boundaries */
103
  isolating: true;
104
}
105
```
106

107
### Node Attributes
108

109
Table header nodes support the following attributes:
110

111
```typescript { .api }
112
interface TableHeaderAttributes {
113
  /** Number of columns the header spans */
114
  colspan: number; // default: 1
115
  /** Number of rows the header spans */
116
  rowspan: number; // default: 1
117
  /** Array of column widths in pixels */
118
  colwidth: number[] | null; // default: null
119
}
120
```
121

122
**Usage with attributes:**
123

124
```typescript
125
// HTML: <th colspan="2" rowspan="1" colwidth="100,150">Header</th>
126
// The extension automatically parses these attributes from HTML
127
```
128

129
### HTML Integration
130

131
The TableHeader extension integrates with standard HTML table markup:
132

133
```typescript { .api }
134
interface HTMLIntegration {
135
  /** Parses th elements from HTML */
136
  parseHTML(): { tag: 'th' }[];
137
  /** Renders as th elements with merged attributes */
138
  renderHTML(options: { HTMLAttributes: Record<string, any> }): ['th', Record<string, any>, 0];
139
}
140
```
141

142
**Example HTML output:**
143

144
```html
145
<th class="custom-header" colspan="1" rowspan="1">
146
  <p>Header content</p>
147
</th>
148
```
149

150
## Configuration Options
151

152
### HTMLAttributes
153

154
Customize the HTML attributes applied to all table header elements:
155

156
```typescript { .api }
157
interface TableHeaderOptions {
158
  HTMLAttributes: Record<string, any>;
159
}
160
```
161

162
**Configuration examples:**
163

164
```typescript
165
// Add CSS classes
166
TableHeader.configure({
167
  HTMLAttributes: {
168
    class: 'table-header-cell',
169
  },
170
});
171

172
// Add inline styles
173
TableHeader.configure({
174
  HTMLAttributes: {
175
    style: 'background-color: #f5f5f5; font-weight: bold;',
176
  },
177
});
178

179
// Add data attributes
180
TableHeader.configure({
181
  HTMLAttributes: {
182
    'data-testid': 'table-header',
183
    'data-role': 'header',
184
  },
185
});
186
```
187

188
## Types
189

190
```typescript { .api }
191
interface TableHeaderOptions {
192
  /**
193
   * The HTML attributes for a table header node.
194
   * @default {}
195
   * @example { class: 'foo' }
196
   */
197
  HTMLAttributes: Record<string, any>;
198
}
199

200
/**
201
 * Tiptap Node extension for creating table header cells (th elements)
202
 * Re-exported from @tiptap/extension-table
203
 */
204
declare const TableHeader: Node<TableHeaderOptions>;
205
```