Skip to content

Add sticky table headers #42837

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mdo wants to merge 2 commits into
base: v6-dev
Choose a base branch
from
+92 −4
Open

Add sticky table headers #42837

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d2fdc1f
Add sticky table headers and tidy table docs
mdo Aug 13, 2026
479b4d9
fix(tables): close the sticky header 1px gap
mdo Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions scss/content/_tables.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ $table-tokens: defaults(
--table-hover-color: var(--table-color),
--table-hover-bg-factor: 7.5%,
--table-hover-bg: color-mix(in srgb, var(--table-color) var(--table-hover-bg-factor), transparent),
--table-thead-sticky-top: 0px,
--table-thead-sticky-zindex: var(--z-3),
),
$table-tokens
);
Expand Down Expand Up @@ -176,6 +178,18 @@ $table-striped-columns-order: even !default;
}
}

// Sticky table headers
//
// Subtract the collapsed cell border so scrolling rows cannot show through a
// 1px gap at the top of the scrollport.

.thead-sticky {
position: sticky;
top: calc(var(--table-thead-sticky-top) - var(--table-border-width, 1px));
z-index: var(--table-thead-sticky-zindex);
background-color: var(--theme-bg-subtle, var(--table-bg));
}

// Responsive tables
//
// Generate `.table-responsive` classes that act as container query contexts
Expand Down
82 changes: 78 additions & 4 deletions site/src/content/docs/content/tables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ Highlight a table row or cell by adding a `.table-active` class.
</table>
`} />

## How do the variants and accented tables work?
## Variants explained

For the accented tables ([striped rows](#striped-rows), [striped columns](#striped-columns), [hoverable rows](#hoverable-rows), and [active tables](#active-tables)), we used some techniques to make these effects work for all our [table variants](#variants):

Expand All @@ -225,7 +225,7 @@ Behind the scenes it looks like this:

## Table borders

### Bordered tables
### Bordered

Add `.table-bordered` for borders on all sides of the table and cells.

Expand All @@ -235,7 +235,7 @@ Add `.table-bordered` for borders on all sides of the table and cells.

<Table class="table table-bordered border-primary" />

### Tables without borders
### No borders

Add `.table-borderless` for a table without borders.

Expand Down Expand Up @@ -427,7 +427,7 @@ Border styles, active styles, and table variants are not inherited by nested tab
</table>
`} />

## How nesting works
### How nesting works

To prevent *any* styles from leaking to nested tables, we use the child combinator (`>`) selector in our CSS. Since we need to target all the `td`s and `th`s in the `thead`, `tbody`, and `tfoot`, our selector would look pretty long without it. As such, we use the rather odd looking `.table > :not(caption) > * > *` selector to target all `td`s and `th`s of the `.table`, but none of any potential nested tables.

Expand Down Expand Up @@ -619,6 +619,80 @@ Both `.table-stacked` and `.table-responsive` use container queries, so the `.ta
</div>
```

## Sticky table headers

Add `.thead-sticky` to a `<thead>` to keep it in view while the table scrolls. Wrap the table in a scrollable container with a max height. Do not put `overflow` on the `<table>` itself—browsers keep that value as `visible`. Set `--bs-table-thead-sticky-top` to offset any fixed headers or navigation above the table.

To prevent additional bleed through from `border-collapse`, we recommend wrapping everything in an extra `overflow-hidden` container.

<Example code={`<div class="overflow-hidden">
<div class="overflow-y-auto" style="max-height: 300px;">
<table class="table mb-0">
<thead class="thead-sticky">
<tr>
<th scope="col">#</th>
<th scope="col">First</th>
<th scope="col">Last</th>
<th scope="col">Handle</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">1</th>
<td>Mark</td>
<td>Otto</td>
<td>@mdo</td>
</tr>
<tr>
<th scope="row">2</th>
<td>Jacob</td>
<td>Thornton</td>
<td>@fat</td>
</tr>
<tr>
<th scope="row">3</th>
<td colspan="2">Larry the Bird</td>
<td>@twitter</td>
</tr>
<tr>
<th scope="row">4</th>
<td>Mark</td>
<td>Otto</td>
<td>@mdo</td>
</tr>
<tr>
<th scope="row">5</th>
<td>Jacob</td>
<td>Thornton</td>
<td>@fat</td>
</tr>
<tr>
<th scope="row">6</th>
<td colspan="2">Larry the Bird</td>
<td>@twitter</td>
</tr>
<tr>
<th scope="row">7</th>
<td>Mark</td>
<td>Otto</td>
<td>@mdo</td>
</tr>
<tr>
<th scope="row">8</th>
<td>Jacob</td>
<td>Thornton</td>
<td>@fat</td>
</tr>
<tr>
<th scope="row">9</th>
<td colspan="2">Larry the Bird</td>
<td>@twitter</td>
</tr>
</tbody>
</table>
</div>
</div>`} />

## Responsive tables

Responsive tables allow tables to be scrolled horizontally with ease. Make any table responsive across all viewports by wrapping a `.table` with `.table-responsive`. Or, pick a maximum breakpoint with which to have a responsive table up to by using `.{sm|md|lg|xl|2xl}:table-responsive`.
Expand Down