Tables in MDX

How to build tables in MDX — basic syntax, alignment tricks, real-world examples, and when tables are actually the right choice.

Tables are for structured data. Rows and columns. MDX uses standard Markdown table syntax, and because it's MDX, you can also drop in React components when you need sorting, filtering, or responsive behavior.

Let's start simple.

Basic Table Syntax

Pipes (|) separate columns. Hyphens (-) separate the header from the body:

mdx example

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
| Cell 7   | Cell 8   | Cell 9   |

Output

| Header 1 | Header 2 | Header 3 |

Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6
Cell 7	Cell 8	Cell 9

Minimal Syntax

You don't technically need the outer pipes or aligned spacing:

mdx example

Header 1 | Header 2 | Header 3
--- | --- | ---
Cell 1 | Cell 2 | Cell 3
Cell 4 | Cell 5 | Cell 6

But honestly, the full syntax is way easier to read in source. Most formatters will auto-align columns anyway, so just use pipes everywhere.

Column Alignment

You control alignment with colons (:) in the separator row:

mdx example

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         |    Center      |         Right |
| Text         |    Text        |          Text |
| Here         |    Here        |          Here |

Here's the rule:

:--- or --- → Left aligned (this is the default)
:---: → Center aligned
---: → Right aligned

A Real Example: Component Props

This is how you'd document props for a component — types centered, defaults centered, descriptions left-aligned:

mdx example

| Property | Type | Default | Description |
|:---------|:----:|:-------:|:------------|
| name     | string | — | Component display name |
| size     | number | `16` | Size in pixels |
| disabled | boolean | `false` | Whether the component is disabled |
| onClick  | function | — | Click event handler |

Numbers Should Be Right-Aligned

When you're showing money, counts, or any numeric data — right-align it. That's how spreadsheets work, and it's easier to scan:

mdx example

| Product        | Q1 Sales | Q2 Sales | Q3 Sales |
|:---------------|----------:|----------:|----------:|
| Widget Pro     | $12,450  | $15,230  | $18,900  |
| Gadget Plus    | $8,300   | $9,100   | $11,200  |
| Tool Master    | $22,100  | $24,500  | $27,800  |
| **Total**      | **$42,850** | **$48,830** | **$57,900** |

Formatting Within Tables

You can use bold, italic, strikethrough, inline code, links, and emoji inside cells:

Example

| Feature | Status | Notes | |:--------|:------:|:------| | **Authentication** | ✅ Complete | Supports OAuth 2.0 | | *Authorization* | 🚧 In Progress | Role-based access | | ~~Legacy API~~ | ❌ Deprecated | Use v3 instead | | `caching` | ✅ Complete | Redis-backed | | [Docs](./docs) | 📄 Available | See link |

API Endpoints Table

This comes up constantly in real docs:

mdx example

| Method | Endpoint | Response |
|:-------|:---------|:---------|
| `GET` | `/api/users` | Array of users |
| `POST` | `/api/users` | Created user |
| `PUT` | `/api/users/:id` | Updated user |
| `DELETE` | `/api/users/:id` | Success message |

Complex Tables

Tables with Long Content

Sometimes cells have a lot of text. That's fine — let them wrap:

mdx example

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `apiKey` | `string` | Your unique API key obtained from the developer dashboard. Required for all authenticated requests. |
| `timeout` | `number` | Maximum time in milliseconds to wait for a response before throwing a timeout error. Defaults to 30000. |
| `retries` | `number` | Number of retry attempts for failed requests. Uses exponential backoff between retries. Defaults to 3. |

Multi-Line Cells

Markdown tables don't support actual line breaks in cells. But you can fake it with <br/>:

mdx example

| Command | Description |
|:--------|:------------|
| `build` | Compiles the project<br/>Outputs to `./dist` folder<br/>Runs type checking |
| `dev` | Starts development server<br/>Enables hot module reload<br/>Opens browser automatically |
| `test` | Runs test suite<br/>Generates coverage report |

Wide Tables

Got a table with tons of columns? Wrap it so it scrolls on small screens:

mdx example

<div style={{ overflowX: 'auto' }}>

| Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 |
|-------|-------|-------|-------|-------|-------|-------|-------|
| Data  | Data  | Data  | Data  | Data  | Data  | Data  | Data  |
| Data  | Data  | Data  | Data  | Data  | Data  | Data  | Data  |

</div>

Responsive Tables

Scrollable Table Wrapper

For anything beyond 4-5 columns, you probably want a wrapper component:

mdx example

import { ResponsiveTable } from '../components/ResponsiveTable'

<ResponsiveTable>

| Browser | Version | Support | Release Date | Engine |
|:--------|:--------|:--------|:-------------|:-------|
| Chrome  | 120+    | Full    | 2023-12-05   | Blink  |
| Firefox | 121+    | Full    | 2023-12-19   | Gecko  |
| Safari  | 17.2+   | Partial | 2023-12-11   | WebKit |
| Edge    | 120+    | Full    | 2023-12-07   | Blink  |

</ResponsiveTable>

jsx example

// components/ResponsiveTable.jsx
export function ResponsiveTable({ children }) {
  return (
    <div className="responsive-table-wrapper" role="region" aria-label="Scrollable table" tabIndex={0}>
      {children}
    </div>
  )
}

Card Layout on Mobile

This is a nice pattern — table on desktop, cards on phones:

Example

// components/AdaptiveTable.jsx — Converts to cards on small screens export function AdaptiveTable({ headers, rows }) { return ( <> {/* Desktop: Regular table */} <table className="desktop-table"> <thead> <tr>{headers.map(h => <th key={h}>{h}</th>)}</tr> </thead> <tbody> {rows.map((row, i) => ( <tr key={i}>{row.map((cell, j) => <td key={j}>{cell}</td>)}</tr> ))} </tbody> </table> {/* Mobile: Card layout */} <div className="mobile-cards"> {rows.map((row, i) => ( <div key={i} className="card"> {row.map((cell, j) => ( <div key={j} className="card-row"> <span className="card-label">{headers[j]}</span> <span className="card-value">{cell}</span> </div> ))} </div> ))} </div> </> ) }

Table Components

Full HTML Table (When Markdown Can't Do It)

Need merged cells? Markdown tables can't handle rowSpan or colSpan. Use HTML:

mdx example

<table>
  <thead>
    <tr>
      <th rowSpan={2}>Name</th>
      <th colSpan={2}>Scores</th>
    </tr>
    <tr>
      <th>Math</th>
      <th>Science</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>95</td>
      <td>88</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>82</td>
      <td>91</td>
    </tr>
  </tbody>
</table>

Comparison Table Component

Pricing pages, feature matrices — you've seen these everywhere:

Example

import { ComparisonTable } from '../components/ComparisonTable' <ComparisonTable headers={['Feature', 'Free', 'Pro', 'Enterprise']} rows={[ ['Users', '5', '50', 'Unlimited'], ['Storage', '1 GB', '100 GB', '1 TB'], ['Support', 'Community', 'Email', '24/7 Priority'], ['API Access', '❌', '✅', '✅'], ['Custom Domain', '❌', '✅', '✅'], ['SSO', '❌', '❌', '✅'], ]} />

Data Table with Props

Pass data as props and let the component handle rendering:

Example

import { DataTable } from '../components/DataTable' <DataTable caption="NPM Package Comparison" data={[ { name: '@mdx-js/react', size: '12kb', downloads: '2.1M/week' }, { name: 'next-mdx-remote', size: '8kb', downloads: '890K/week' }, { name: 'mdx-bundler', size: '15kb', downloads: '340K/week' }, ]} columns={[ { key: 'name', label: 'Package', align: 'left' }, { key: 'size', label: 'Bundle Size', align: 'right' }, { key: 'downloads', label: 'Weekly Downloads', align: 'right' }, ]} />

Sortable Tables

Markdown tables are static. But in MDX, you can make them clickable and sortable:

Example

import { SortableTable } from '../components/SortableTable' <SortableTable columns={[ { key: 'name', label: 'Framework', sortable: true }, { key: 'stars', label: 'GitHub Stars', sortable: true, type: 'number' }, { key: 'license', label: 'License', sortable: true }, ]} data={[ { name: 'Next.js', stars: 118000, license: 'MIT' }, { name: 'Gatsby', stars: 55000, license: 'MIT' }, { name: 'Remix', stars: 26000, license: 'MIT' }, { name: 'Astro', stars: 38000, license: 'MIT' }, ]} defaultSort="stars" defaultDirection="desc" />

How to Build One

Here's a basic implementation. Nothing fancy — just useState and .sort():

Example

// components/SortableTable.jsx import { useState } from 'react' export function SortableTable({ columns, data, defaultSort, defaultDirection }) { const [sortKey, setSortKey] = useState(defaultSort) const [direction, setDirection] = useState(defaultDirection || 'asc') const sorted = [...data].sort((a, b) => { const aVal = a[sortKey] const bVal = b[sortKey] const modifier = direction === 'asc' ? 1 : -1 if (typeof aVal === 'number') return (aVal - bVal) * modifier return aVal.localeCompare(bVal) * modifier }) const handleSort = (key) => { if (key === sortKey) setDirection(d => d === 'asc' ? 'desc' : 'asc') else { setSortKey(key); setDirection('asc') } } return ( <table className="sortable-table"> <thead> <tr> {columns.map(col => ( <th key={col.key} onClick={() => col.sortable && handleSort(col.key)} className={col.sortable ? 'sortable' : ''}> {col.label} {sortKey === col.key && (direction === 'asc' ? '↑' : '↓')} </th> ))} </tr> </thead> <tbody> {sorted.map((row, i) => ( <tr key={i}> {columns.map(col => <td key={col.key}>{row[col.key]}</td>)} </tr> ))} </tbody> </table> ) }

When to Use Tables (And When Not To)

Tables are great for:

Comparing items across the same attributes
Numeric data, specs, pricing
Config options with types and defaults
API endpoint docs
Feature comparison matrices

Use a list instead when:

mdx example

{/* ❌ BAD — Simple data forced into a table */}
| Requirement |
|-------------|
| Node.js 18+ |
| npm 9+      |
| Git 2.0+    |

{/* ✅ GOOD — A simple list is more appropriate */}
**Requirements:**
- Node.js 18+
- npm 9+
- Git 2.0+

If you've got a single column, it's not really a table. It's a list.

Use definition lists instead when:

mdx example

{/* ❌ BAD — Key-value pairs in a table */}
| Term | Definition |
|------|------------|
| API  | Application Programming Interface |
| SDK  | Software Development Kit |

{/* ✅ GOOD — Definition list is more semantic */}
<dl>
  <dt>API</dt>
  <dd>Application Programming Interface</dd>
  <dt>SDK</dt>
  <dd>Software Development Kit</dd>
</dl>

Just write prose when:

You have 2-3 items with short descriptions. A sentence is clearer than a table with two rows.

Best Practices

Always include headers — A table without headers is just a grid of confusion.
Keep it under 6-7 columns — Too wide? Split into multiple tables.
Right-align numbers, left-align text — This isn't a style choice, it's readability.
Add a caption or heading — Tell people what they're looking at.
Think about mobile — Wide tables need scroll wrappers.
Keep cells short — Long paragraphs don't belong in table cells.

Common Mistakes

Inconsistent Column Counts

mdx example

{/* ❌ BAD — Rows have different numbers of cells */}
| A | B | C |
|---|---|---|
| 1 | 2 |
| 4 | 5 | 6 | 7 |

{/* ✅ GOOD — Consistent column count */}
| A | B | C |
|---|---|---|
| 1 | 2 | — |
| 4 | 5 | 6 |

Missing Separator Row

mdx example

{/* ❌ BAD — No separator between header and body */}
| Header 1 | Header 2 |
| Cell 1   | Cell 2   |

{/* ✅ GOOD — Separator row required */}
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Pipe Characters in Cell Content

mdx example

{/* ❌ BAD — Unescaped pipe breaks the table */}
| Command | Example |
|---------|---------|
| OR      | a | b   |

{/* ✅ GOOD — Escape the pipe */}
| Command | Example |
|---------|---------|
| OR      | a \| b  |

Cramming Too Much Into One Table

mdx example

{/* ❌ BAD — Too much data crammed into a table */}
{/* Consider breaking into multiple smaller tables or using a component */}

{/* ✅ GOOD — Split complex tables */}
{/* Table 1: Basic properties */}
{/* Table 2: Advanced properties */}
{/* Table 3: Event handlers */}

Quick Reference

Feature	Syntax
Basic table	`\	H \	H \	`+` \	---\	---\	`+` \	C \	C \	`
Left align	`:---`
Center align	`:---:`
Right align	`---:`
Escape pipe	`\	`
Multi-line cell	`<br/>`
Spanning cells	HTML `colSpan`/`rowSpan`

That's tables. Use them when you have real structured data to show. Don't force everything into a grid just because you can.

Let's start simple.

Basic Table Syntax

Pipes (|) separate columns. Hyphens (-) separate the header from the body:

mdx example

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
| Cell 7   | Cell 8   | Cell 9   |

Output

| Header 1 | Header 2 | Header 3 |

Cell 1	Cell 2	Cell 3
Cell 4	Cell 5	Cell 6
Cell 7	Cell 8	Cell 9

Minimal Syntax

You don't technically need the outer pipes or aligned spacing:

mdx example

Header 1 | Header 2 | Header 3
--- | --- | ---
Cell 1 | Cell 2 | Cell 3
Cell 4 | Cell 5 | Cell 6

But honestly, the full syntax is way easier to read in source. Most formatters will auto-align columns anyway, so just use pipes everywhere.

Column Alignment

You control alignment with colons (:) in the separator row:

mdx example

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         |    Center      |         Right |
| Text         |    Text        |          Text |
| Here         |    Here        |          Here |

Here's the rule:

:--- or --- → Left aligned (this is the default)
:---: → Center aligned
---: → Right aligned

A Real Example: Component Props

This is how you'd document props for a component — types centered, defaults centered, descriptions left-aligned:

mdx example

| Property | Type | Default | Description |
|:---------|:----:|:-------:|:------------|
| name     | string | — | Component display name |
| size     | number | `16` | Size in pixels |
| disabled | boolean | `false` | Whether the component is disabled |
| onClick  | function | — | Click event handler |

Numbers Should Be Right-Aligned

When you're showing money, counts, or any numeric data — right-align it. That's how spreadsheets work, and it's easier to scan:

mdx example

| Product        | Q1 Sales | Q2 Sales | Q3 Sales |
|:---------------|----------:|----------:|----------:|
| Widget Pro     | $12,450  | $15,230  | $18,900  |
| Gadget Plus    | $8,300   | $9,100   | $11,200  |
| Tool Master    | $22,100  | $24,500  | $27,800  |
| **Total**      | **$42,850** | **$48,830** | **$57,900** |

Formatting Within Tables

You can use bold, italic, strikethrough, inline code, links, and emoji inside cells:

Example

API Endpoints Table

This comes up constantly in real docs:

mdx example

| Method | Endpoint | Response |
|:-------|:---------|:---------|
| `GET` | `/api/users` | Array of users |
| `POST` | `/api/users` | Created user |
| `PUT` | `/api/users/:id` | Updated user |
| `DELETE` | `/api/users/:id` | Success message |

Complex Tables

Tables with Long Content

Sometimes cells have a lot of text. That's fine — let them wrap:

mdx example

| Parameter | Type | Description |
|:----------|:-----|:------------|
| `apiKey` | `string` | Your unique API key obtained from the developer dashboard. Required for all authenticated requests. |
| `timeout` | `number` | Maximum time in milliseconds to wait for a response before throwing a timeout error. Defaults to 30000. |
| `retries` | `number` | Number of retry attempts for failed requests. Uses exponential backoff between retries. Defaults to 3. |

Multi-Line Cells

Markdown tables don't support actual line breaks in cells. But you can fake it with <br/>:

mdx example

| Command | Description |
|:--------|:------------|
| `build` | Compiles the project<br/>Outputs to `./dist` folder<br/>Runs type checking |
| `dev` | Starts development server<br/>Enables hot module reload<br/>Opens browser automatically |
| `test` | Runs test suite<br/>Generates coverage report |

Wide Tables

Got a table with tons of columns? Wrap it so it scrolls on small screens:

mdx example

<div style={{ overflowX: 'auto' }}>

| Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 |
|-------|-------|-------|-------|-------|-------|-------|-------|
| Data  | Data  | Data  | Data  | Data  | Data  | Data  | Data  |
| Data  | Data  | Data  | Data  | Data  | Data  | Data  | Data  |

</div>

Responsive Tables

Scrollable Table Wrapper

For anything beyond 4-5 columns, you probably want a wrapper component:

mdx example

import { ResponsiveTable } from '../components/ResponsiveTable'

<ResponsiveTable>

| Browser | Version | Support | Release Date | Engine |
|:--------|:--------|:--------|:-------------|:-------|
| Chrome  | 120+    | Full    | 2023-12-05   | Blink  |
| Firefox | 121+    | Full    | 2023-12-19   | Gecko  |
| Safari  | 17.2+   | Partial | 2023-12-11   | WebKit |
| Edge    | 120+    | Full    | 2023-12-07   | Blink  |

</ResponsiveTable>

jsx example

// components/ResponsiveTable.jsx
export function ResponsiveTable({ children }) {
  return (
    <div className="responsive-table-wrapper" role="region" aria-label="Scrollable table" tabIndex={0}>
      {children}
    </div>
  )
}

Card Layout on Mobile

This is a nice pattern — table on desktop, cards on phones:

Example

Table Components

Full HTML Table (When Markdown Can't Do It)

Need merged cells? Markdown tables can't handle rowSpan or colSpan. Use HTML:

mdx example

<table>
  <thead>
    <tr>
      <th rowSpan={2}>Name</th>
      <th colSpan={2}>Scores</th>
    </tr>
    <tr>
      <th>Math</th>
      <th>Science</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>95</td>
      <td>88</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>82</td>
      <td>91</td>
    </tr>
  </tbody>
</table>

Comparison Table Component

Pricing pages, feature matrices — you've seen these everywhere:

Example

Data Table with Props

Pass data as props and let the component handle rendering:

Example

Sortable Tables

Markdown tables are static. But in MDX, you can make them clickable and sortable:

Example

How to Build One

Here's a basic implementation. Nothing fancy — just useState and .sort():

Example

When to Use Tables (And When Not To)

Tables are great for:

Comparing items across the same attributes
Numeric data, specs, pricing
Config options with types and defaults
API endpoint docs
Feature comparison matrices

Use a list instead when:

mdx example

{/* ❌ BAD — Simple data forced into a table */}
| Requirement |
|-------------|
| Node.js 18+ |
| npm 9+      |
| Git 2.0+    |

{/* ✅ GOOD — A simple list is more appropriate */}
**Requirements:**
- Node.js 18+
- npm 9+
- Git 2.0+

If you've got a single column, it's not really a table. It's a list.

Use definition lists instead when:

mdx example

{/* ❌ BAD — Key-value pairs in a table */}
| Term | Definition |
|------|------------|
| API  | Application Programming Interface |
| SDK  | Software Development Kit |

{/* ✅ GOOD — Definition list is more semantic */}
<dl>
  <dt>API</dt>
  <dd>Application Programming Interface</dd>
  <dt>SDK</dt>
  <dd>Software Development Kit</dd>
</dl>

Just write prose when:

You have 2-3 items with short descriptions. A sentence is clearer than a table with two rows.

Best Practices

Always include headers — A table without headers is just a grid of confusion.
Keep it under 6-7 columns — Too wide? Split into multiple tables.
Right-align numbers, left-align text — This isn't a style choice, it's readability.
Add a caption or heading — Tell people what they're looking at.
Think about mobile — Wide tables need scroll wrappers.
Keep cells short — Long paragraphs don't belong in table cells.

Common Mistakes

Inconsistent Column Counts

mdx example

{/* ❌ BAD — Rows have different numbers of cells */}
| A | B | C |
|---|---|---|
| 1 | 2 |
| 4 | 5 | 6 | 7 |

{/* ✅ GOOD — Consistent column count */}
| A | B | C |
|---|---|---|
| 1 | 2 | — |
| 4 | 5 | 6 |

Missing Separator Row

mdx example

{/* ❌ BAD — No separator between header and body */}
| Header 1 | Header 2 |
| Cell 1   | Cell 2   |

{/* ✅ GOOD — Separator row required */}
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Pipe Characters in Cell Content

mdx example

{/* ❌ BAD — Unescaped pipe breaks the table */}
| Command | Example |
|---------|---------|
| OR      | a | b   |

{/* ✅ GOOD — Escape the pipe */}
| Command | Example |
|---------|---------|
| OR      | a \| b  |

Cramming Too Much Into One Table

mdx example

{/* ❌ BAD — Too much data crammed into a table */}
{/* Consider breaking into multiple smaller tables or using a component */}

{/* ✅ GOOD — Split complex tables */}
{/* Table 1: Basic properties */}
{/* Table 2: Advanced properties */}
{/* Table 3: Event handlers */}

Quick Reference

Feature	Syntax
Basic table	`\	H \	H \	`+` \	---\	---\	`+` \	C \	C \	`
Left align	`:---`
Center align	`:---:`
Right align	`---:`
Escape pipe	`\	`
Multi-line cell	`<br/>`
Spanning cells	HTML `colSpan`/`rowSpan`

That's tables. Use them when you have real structured data to show. Don't force everything into a grid just because you can.

Basic Table Syntax

Minimal Syntax

Column Alignment

A Real Example: Component Props

Numbers Should Be Right-Aligned

Formatting Within Tables

API Endpoints Table

Complex Tables

Tables with Long Content

Multi-Line Cells

Wide Tables

Responsive Tables

Scrollable Table Wrapper

Card Layout on Mobile

Table Components

Full HTML Table (When Markdown Can't Do It)

Comparison Table Component

Data Table with Props

Sortable Tables

How to Build One

When to Use Tables (And When Not To)

Tables are great for:

Use a list instead when:

Use definition lists instead when:

Just write prose when:

Best Practices

Common Mistakes

Inconsistent Column Counts

Missing Separator Row

Pipe Characters in Cell Content

Cramming Too Much Into One Table

Quick Reference

Continue learning this concept

Basic Table Syntax

Minimal Syntax

Column Alignment

A Real Example: Component Props

Numbers Should Be Right-Aligned

Formatting Within Tables

API Endpoints Table

Complex Tables

Tables with Long Content

Multi-Line Cells

Wide Tables

Responsive Tables

Scrollable Table Wrapper

Card Layout on Mobile

Table Components

Full HTML Table (When Markdown Can't Do It)

Comparison Table Component

Data Table with Props

Sortable Tables

How to Build One

When to Use Tables (And When Not To)

Tables are great for:

Use a list instead when:

Use definition lists instead when:

Just write prose when:

Best Practices

Common Mistakes

Inconsistent Column Counts

Missing Separator Row

Pipe Characters in Cell Content

Cramming Too Much Into One Table

Quick Reference

Continue learning this concept