`, `| `, and ` | `. BEEQ styles apply only when the `bq-table` class is present on the `` element.
## When to use
Use tables when
* You need to display multiple attributes of multiple items simultaneously
* Users need to scan, compare, or sort across rows
* Data has a natural row-and-column structure, such as transactions, records, or reports
* Inline actions such as editing or deleting a row belong next to each record
Do not use tables when
* You only need to display a single attribute per item — a list is simpler
* The data is non-comparative prose or narrative content
* You need a layout grid — use CSS Grid or Flexbox instead
* The number of columns is very large and the content would be better served by a detail page
## Patterns
Add a trailing actions column containing a dropdown or icon buttons to let users edit, delete, or navigate to a detail view for each row.
Apply `.selected` to a `` to visually indicate the active or focused record, for example when a row drives a side panel or detail pane.
Use the `.compact` modifier in dense dashboards or administrative interfaces where vertical space matters more than breathing room.
Use `.bordered` when each cell needs an explicit boundary, such as in financial or spreadsheet-style tables where column delineation helps readability.
## Anatomy
A table is built from standard HTML sectioning and cell elements. Each part has a defined role and styling responsibility.
| Part | Element | Description |
| ----- | -------------------------- | ------------------------------------------------------------- |
| **1** | `` | Root element that activates BEEQ table styles |
| **2** | `` | Header section containing column labels |
| **3** | `| ` | Header cell for a single column |
| **4** | ` | ` | Body section containing data rows |
| **5** | `` | A single data row; add `.selected` for the active state |
| **6** | `` | A single data cell |
| **7** | `.bq-table--container` | Optional responsive wrapper that enables horizontal scrolling |
## Design guidelines
The default table uses generous cell padding to give content room to breathe. Use it in most contexts where the dataset fits comfortably on screen.
The `.compact` modifier reduces padding significantly. Reserve it for dashboards or administrative screens where showing more rows at once outweighs the reduced spacing.
The default style separates rows with a single bottom border and uses subtle column dividers in the header only. This keeps the table light and easy to scan.
Adding `.bordered` draws a full border around every cell and the table itself. Use this when column delineation is critical for data clarity, such as financial or spreadsheet-style tables.
Wrap the table in `.bq-table--container` to enable horizontal scrolling on smaller screens. Without this wrapper, wide tables may overflow their parent container.
## Usage
### Default
The default table applies base typography, header and cell padding, and row separators. Add the `bq-table` class to any standard `` element to activate the styles.
body {
padding: var(--bq-spacing-m);
}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
@Component({
selector: "app-root",
standalone: true,
imports: [],
template: `
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
## Options
### Selected row
Add the `selected` class to a `` to highlight the active record. Use this when a row selection drives a side panel, detail view, or other contextual UI.
body {
padding: var(--bq-spacing-m);
}
| Name |
Status |
Amount |
| John Doe |
Active |
-2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
-2,343 € |
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
@Component({
selector: "app-root",
standalone: true,
imports: [],
template: `
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
### Compact
Add the `compact` class to the `` to reduce cell and header padding. This is useful in dense, data-heavy interfaces where vertical space is at a premium.
body {
padding: var(--bq-spacing-m);
}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
@Component({
selector: "app-root",
standalone: true,
imports: [],
template: `
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
### Bordered
Add the `bordered` class to draw explicit borders around each cell and the table itself. Use this when strong column delineation helps users parse the data.
body {
padding: var(--bq-spacing-m);
}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
@Component({
selector: "app-root",
standalone: true,
imports: [],
template: `
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
| Name |
Status |
Amount |
| John Doe |
Active |
−2,343 € |
| Alice Smith |
Pending |
+95,453 € |
| Robert Johnson |
Inactive |
−2,343 € |
```
## Best practices
Do
Always wrap the table in `.bq-table--container` so it scrolls horizontally on small screens instead of overflowing.
Don't
Let a wide table overflow its parent without a scroll container — this breaks the page layout on narrow viewports.
Do
Keep column headers short and descriptive so users understand each column without reading the data first.
Don't
Use abbreviations or internal codes in headers without a tooltip or legend to explain them.
Do
Align numeric values to the trailing edge of the cell so decimal points and magnitudes line up across rows.
Don't
Mix left-aligned and center-aligned numeric columns in the same table — inconsistent alignment makes comparison harder.
Do
Choose the density that matches the user's task — default for reading and reviewing, compact for monitoring and bulk operations.
Don't
Apply the compact modifier to fit more rows when it makes the content harder to read or interact with.
## Accessibility
* You must: provide a `` or `aria-label` on the `` element so screen readers announce the table's purpose before reading the data.
* You must: use `` elements with the correct `scope` attribute (`scope="col"` for column headers, `scope="row"` for row headers) so assistive technologies can map each cell to its headers.
* You must: keep the table structure semantic — do not use a `` for layout purposes.
* You must: ensure inline action elements inside cells (buttons, dropdowns) have accessible labels, especially icon-only controls.
* You must: when a row selection changes UI state (such as opening a side panel), communicate that change programmatically — for example by managing focus or using a live region.
* Built in: the `.selected` row styling uses `outline` rather than `border` so the selection indicator does not affect layout. There is no automatic ARIA state applied; add `aria-selected="true"` to the `` when the row is interactively selectable.
## API reference
### CSS classes
The table pattern is CSS-only. There is no custom element. Apply these classes to standard HTML elements:
| Class | Element | Description |
| --------------------- | --------- | ------------------------------------------------------ |
| `bq-table` | `` | **Required.** Activates all BEEQ table styles |
| `compact` | `` | Reduces cell and header padding for dense layouts |
| `bordered` | `` | Draws explicit borders around every cell and the table |
| `selected` | `` | Highlights the row as the active or selected record |
| `bq-table--container` | `` | Responsive wrapper that enables horizontal scrolling |
### CSS custom properties
| Variable | Description | Default |
| ----------------------------------- | --------------------------------------------------------- | --------------------------- |
| `--bq-table--border-color` | Border color for dividers and cell borders | `var(--bq-stroke--primary)` |
| `--bq-table--border-style` | Border style for dividers and cell borders | `solid` |
| `--bq-table--border-width` | Border width for dividers and cell borders | `var(--bq-stroke-s)` |
| `--bq-table--border-radius` | Border radius for bordered table corners and selected row | `var(--bq-radius--m)` |
| `--bq-table--cell-padding-block` | Block (vertical) padding for data cells | `var(--bq-spacing-m)` |
| `--bq-table--cell-padding-inline` | Inline (horizontal) padding for data cells | `var(--bq-spacing-m)` |
| `--bq-table--header-divider-inset` | Vertical inset for the column divider line in `| ` | `25%` |
| `--bq-table--header-height` | Height of the `` row | `3.25rem` |
| `--bq-table--header-padding-block` | Block (vertical) padding for header cells | `var(--bq-spacing-xs)` |
| `--bq-table--header-padding-inline` | Inline (horizontal) padding for header cells | `var(--bq-spacing-m)` |
| `--bq-table--row-selected-bg` | Background color of a selected row | `var(--bq-ui--brand-alt)` |
| `--bq-table--row-selected-border` | Outline color of a selected row | `var(--bq-stroke--brand)` |
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore table variants and states in Storybook.
View the table styles source on GitHub.
| | | |
Tables organize information into rows and columns so people can compare values, find records, and take action on individual items. BEEQ styles the native HTML `