Skip to main content
BEEQ Table component overviewBEEQ Table component overview

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

Add the bordered modifier to a table that already has the bq-table class when each cell needs an explicit boundary, such as in financial or spreadsheet-style tables.

Large datasets

BEEQ does not ship a pagination, sorting, filtering, or virtualization component. Render only the current page of rows yourself, then compose page controls from bq-button, bq-select, or bq-input to let users move between pages.

​
Anatomy

A table is built from standard HTML sectioning and cell elements. Each part has a defined role and styling responsibility.

​
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

Allowed modifier classes: compact and bordered on <table class="bq-table"> (neither is on by default), and selected on <tr>. Density is default unless compact is set. Each modifier works only together with the bq-table class.

​
Selected row

Add the selected class to a <tr> to highlight the active record. Use it 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 bordered alongside bq-table to draw borders around each cell and the table itself. This modifier switches to separate cell borders with zero spacing; bordered alone does not enable BEEQ table styles.

​
Pagination and large datasets

BEEQ does not ship a pagination, sorting, filtering, or virtualization component, and the bq-table class does not read from a data source. You render the current page of rows yourself in your framework, then build the page controls from existing BEEQ components — typically bq-button for previous and next, and bq-select for the page size.
Announce page changes for screen reader users. This example updates a polite live region after each transition; move focus to the first cell when the new page must become the next task.

​
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. You must not use a <table> for layout purposes.
  • You must give inline action elements inside cells (buttons, dropdowns) accessible labels, especially icon-only controls.
  • When a row selection changes UI state (such as opening a side panel), you must 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; you should add aria-selected="true" to the <tr> when the row is interactively selectable.

​
Keyboard interaction

No keyboard interaction: the component is not focusable. The table styles add no focusable elements; buttons, links, and dropdowns you place in cells follow their own keyboard behavior.

​
Rules

​
API reference

​
CSS classes

The table pattern is CSS-only. There is no custom element. Apply these classes to standard HTML elements:

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