td
The td element defines a data cell in a table. Vanilla Breeze styles cells with a thin bottom border and top vertical alignment. Supports data attributes for numeric alignment, custom sort/filter values, and responsive card-mode labels.
Description
The <td> (table data) element contains a cell of data in a table. Data cells are associated with header cells (<th>) through the table structure, primarily via the scope attribute on headers.
Vanilla Breeze styles data cells with consistent padding (var(--size-s) var(--size-m)), top vertical alignment, and a thin bottom border (var(--border-width-thin)). Row hover effects highlight the entire <tr> containing the cell.
When to Use
- Data values: All cells containing actual data (not headers)
- tbody cells: The primary content within
<tbody>rows - tfoot cells: Summary/total values in
<tfoot> - Empty cells: Placeholder cells to maintain column alignment (use "N/A" or "-" rather than leaving blank)
When to Use th Instead
- Column headers: Use
<th scope="col">in<thead> - Row headers: Use
<th scope="row">when the first cell identifies the row
Examples
Basic Data Cells
Data cells contain the values described by column and row headers.
<tbody> <tr> <td>Wireless Mouse</td> <td>Peripherals</td> <td>WM-001</td> <td data-numeric>245</td> </tr></tbody>Numeric Data
Use the data-numeric attribute for cells containing numbers. This right-aligns the content and applies font-variant-numeric: tabular-nums so digits align vertically across rows.
<td data-numeric>$37,500.00</td><td data-numeric>+12.5%</td><td data-numeric>1,480</td>Explicit Alignment
Use data-align when the default (start) or data-numeric (end) are not appropriate for the content.
<td data-align="start">Left-aligned text</td><td data-align="center">Centered status</td><td data-align="end">Right-aligned value</td>Custom Sort Values
Use data-sort-value when the display text differs from the value that should be used for sorting. The <data-table> component reads this attribute during sort operations.
<!-- Display shows friendly text, sort uses ISO date --><td data-sort-value="2026-03-08">Mar 8, 2026</td> <!-- Display shows formatted number, sort uses raw value --><td data-numeric data-sort-value="37500">$37,500</td> <!-- Display shows status text, sort uses numeric priority --><td data-sort-value="1">Critical</td>Custom Filter Values
Use data-filter-value when the cell's display content does not capture all the text a user might search for. The <data-table> component uses this for its filter/search feature.
<!-- Filter matches on normalized value, not display text --><td data-filter-value="electronics peripherals"> <strong>Wireless Mouse</strong><br /> <small>Peripherals · Electronics</small></td> <!-- Filter matches alternate spellings or abbreviations --><td data-filter-value="united states usa america"> United States</td>Responsive Card-Mode Labels
On narrow screens, the <data-table> component can switch from a traditional table layout to a stacked card layout. Add data-label to each <td> to provide the column header text that appears as a label in card mode.
<!-- data-label provides column headers in card mode --><tr> <td data-label="Product">Wireless Mouse</td> <td data-label="Category">Peripherals</td> <td data-label="SKU">WM-001</td> <td data-label="Stock" data-numeric>245</td></tr>Complex Header Associations
For tables with multiple levels of headers where automatic association via scope is insufficient, use the headers attribute to explicitly list the IDs of the associated header cells.
<table> <thead> <tr> <th id="product">Product</th> <th id="q1">Q1</th> <th id="q2">Q2</th> </tr> </thead> <tbody> <tr> <th id="widget" scope="row">Widget</th> <td headers="widget q1">$12,500</td> <td headers="widget q2">$15,200</td> </tr> </tbody></table>VB Data Attributes
| Attribute | Values | Description |
|---|---|---|
data-numeric |
Boolean attribute | Right-aligns content and uses tabular numerals |
data-align |
start, center, end |
Explicit text alignment override |
data-sort-value |
String | Value used for sorting (overrides display text) |
data-filter-value |
String | Value used for filtering/search (overrides display text) |
data-label |
String | Column header label for responsive card mode |
Standard HTML Attributes
| Attribute | Values | Description |
|---|---|---|
colspan |
Positive integer | Number of columns the cell spans |
rowspan |
Positive integer | Number of rows the cell spans |
headers |
Space-separated IDs | Explicitly associates cell with header cells |
CSS Reference
td { padding: var(--size-s) var(--size-m); border-block-end: var(--border-width-thin) solid var(--color-border); vertical-align: top; text-align: start;} /* Numeric alignment */td[data-numeric] { text-align: end; font-variant-numeric: tabular-nums;} /* Explicit alignment */td[data-align="start"] { text-align: start; }td[data-align="center"] { text-align: center; }td[data-align="end"] { text-align: end; } /* Card-mode label (responsive tables) */td[data-label]::before { content: attr(data-label); font-weight: 600; display: block;}Accessibility
- Header associations: Data cells are automatically associated with their column and row headers through the table structure and
scope - Screen reader navigation: When navigating to a
<td>, screen readers announce the associated headers - Complex tables: Use the
headersattribute when automatic association is insufficient - Avoid empty cells: Use meaningful placeholders like "N/A" or "-" for better screen reader experience
- Rich content: When cells contain structured content (links, buttons, status badges), ensure all interactive elements are keyboard accessible