Skip to main content
BEEQ Table component overview
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 <table> element with CSS utility classes instead of shipping a custom web component.
Because the table is a CSS-only pattern, you own the correct HTML structure: <table>, <thead>, <tbody>, <tr>, <th>, and <td>. BEEQ styles apply only when the bq-table class is present on the <table> 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

Data grid with actions

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.

Selected row highlight

Apply .selected to a <tr> to visually indicate the active or focused record, for example when a row drives a side panel or detail pane.

Compact density

Use the .compact modifier in dense dashboards or administrative interfaces where vertical space matters more than breathing room.

Bordered layout

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.
BEEQ Table anatomy
PartElementDescription
1<table class="bq-table">Root element that activates BEEQ table styles
2<thead>Header section containing column labels
3<th>Header cell for a single column
4<tbody>Body section containing data rows
5<tr>A single data row; add .selected for the active state
6<td>A single data cell
7.bq-table--containerOptional responsive wrapper that enables horizontal scrolling

​
Design guidelines

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 <table> element to activate the styles.

​
Options

​
Selected row

Add the selected class to a <tr> to highlight the active record. Use this when a row selection drives a side panel, detail view, or other contextual UI.

​
Compact

Add the compact class to the <table> to reduce cell and header padding. This is useful in dense, data-heavy interfaces where vertical space is at a premium.

​
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.

​
Best practices

DoAlways wrap the table in .bq-table--container so it scrolls horizontally on small screens instead of overflowing.

Don’tLet a wide table overflow its parent without a scroll container — this breaks the page layout on narrow viewports.

DoKeep column headers short and descriptive so users understand each column without reading the data first.

Don’tUse abbreviations or internal codes in headers without a tooltip or legend to explain them.

DoAlign numeric values to the trailing edge of the cell so decimal points and magnitudes line up across rows.

Don’tMix left-aligned and center-aligned numeric columns in the same table — inconsistent alignment makes comparison harder.

DoChoose the density that matches the user’s task — default for reading and reviewing, compact for monitoring and bulk operations.

Don’tApply the compact modifier to fit more rows when it makes the content harder to read or interact with.

​
Accessibility

  • You must: provide a <caption> or aria-label on the <table> element so screen readers announce the table’s purpose before reading the data.
  • You must: use <th> 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 <table> 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 <tr> 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:
ClassElementDescription
bq-table<table>Required. Activates all BEEQ table styles
compact<table>Reduces cell and header padding for dense layouts
bordered<table>Draws explicit borders around every cell and the table
selected<tr>Highlights the row as the active or selected record
bq-table--container<div>Responsive wrapper that enables horizontal scrolling

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore table variants and states in Storybook.

Source code

View the table styles source on GitHub.