Data Table

Data Structure

The q2-data-table has two different properties that you are responsible for providing data to. One is headers , and the other is rows. Below are type definitions of both.

Header Data Structure

The data you provide to the headers property will be an array of objects with the following data structure.

interface Q2DataTableHeader {
  title: string;

  // Will be autogenerated from the title if not provided
  // The key is used to grab the data from the row data
  key?: string;

  // 'auto' to use built-in sorting for this column
  // 'manual' to implement your own sorting for this column
  sortable?: 'auto' | 'manual';

  // Indicates in what direction the data is sorted
  sorted?: 'ASC' | 'DESC';

  // Limits the number of rows that are displayed in a cell
  // Content will be truncated if it exceeds the limit
  lineClamp?: number;


  // Defines alignment of the content within each cell in this column
  // Defaults to 'center'
  align?: 'start' | 'center' | 'end';
  verticalAlign?: 'top' | 'bottom';
  ariaLabel?: string;

  // Defines the width of the column
  width?: string;

  // Defines the background of the column
  backgroundColor?: string;

  // Defines the content type for every cell in this column for styling puposes
  type?: 'text' | 'number' | 'icon' | 'badge' | 'boolean' | 'code';

  // When type = 'badge' - for single badge display
  badgeStatus?: 'info' | 'alert' | 'warning' | 'success';
  badgeTheme?: 'primary' | 'secondary' | 'tertiary';

  // When type = 'badge' - for multiple tags display
  // If tags array is provided, it takes precedence over single badge properties
  tags?: {
    value: any;
    badgeTheme: 'primary' | 'secondary' | 'tertiary';
  }[];
}

Row Data Structure

Similarly, the data you pass to rows is an array of objects with the following structure.

interface Q2DataTableRow {
  id: string | number;
  selected?: boolean;
  expanded?: boolean;
  disabled?: boolean;
  cells: Record<string, string | number | Q2DataTableCell>
}

interface Q2DataTableCell {
  value: string | number;

  // Defines alignment of the content within this cell
  // Takes priority over the column's `align` property when provided
  // Defaults to 'center'
  align?: 'start' | 'center' | 'end';
  verticalAlign?: 'top' | 'bottom';
  ariaLabel?: string;


  // Defines the content type for this cell for styling purposes
  // Takes priority over the column's `type` property when provided
  type?: 'text' | 'number' | 'icon' | 'badge' | 'boolean' | 'code';

  // Limits the number of rows that are displayed in a cell
  // Content will be truncated if it exceeds the limit
  lineClamp?: number;

  // When type = 'badge' - for single badge display
  badgeStatus?: 'info' | 'alert' | 'warning' | 'success';
  badgeTheme?: 'primary' | 'secondary' | 'tertiary';

  // When type = 'badge' - for multiple tags display
  // If tags array is provided, it takes precedence over single badge properties
  tags?: {
    value: any;
    badgeTheme: 'primary' | 'secondary' | 'tertiary';
  }[];
}

Sample

With that said, let's look at a sample set of data that you can provide to a q2-data-table to be displayed.

const headerData = [
  {
    title: 'Day of Week',
    key: 'day',
    backgroundColor: 'var(--t-gray-14)',
  },
  { title: 'Sales', key: 'sales', align: 'center' },
  { title: 'Revenue', key: 'revenue', align: 'center', sortable: true },
];

const rowData = [
  {
    id: 1,
    cells: {
      day: 'Monday',
      sales: 93,
      revenue: '$4,650',
    },
  },
  {
    id: 2,
    cells: {
      day: 'Tuesday',
      sales: 127,
      revenue: '$6,350',
    },
  },
  {
    id: 3,
    cells: {
      day: 'Wednesday',
      sales: 121,
      revenue: '$6,050',
    },
  },
  {
    id: 4,
    cells: {
      day: 'Thursday',
      sales: 140,
      revenue: '$7,000',
    },
  },
  {
    id: 5,
    cells: {
      day: 'Friday',
      sales: 83,
      revenue: '$4,150',
    },
  },
];

From here, you need to provide the q2-data-table with this data:

const salesTable = document.querySelector('q2-data-table');
salesTable.headers = headerData;
salesTable.rows = rowData;

Badge Columns with Multiple Tags

Badge columns can display multiple tags instead of a single badge by providing a tags array in the cell data. This is useful for showing categories, multiple statuses, or collections of labels for a given row. When the tags array is provided, the component will render multiple q2-tag components in a flexible, wrapping layout instead of a single q2-badge.

When to Use Each Mode

• Single Badge: Use for status indicators, counts, or single values (e.g., "Active", "5 items", "Warning")
• Multiple Tags: Use for categories, multiple statuses, or collections of labels (e.g., ["Feature", "Priority"], ["Approved", "Reviewed"])

Header Configuration for Badge Column

To configure a column for badge display, set type: 'badge' in the header data:

const headerData = [
  { title: 'Product', key: 'product' },
  { title: 'Categories', key: 'categories', type: 'badge', align: 'center' },
  { title: 'Price', key: 'price', align: 'end' }
];

Row Configuration with Multiple Tags

For each row, provide a tags array in the cell object. Each tag in the array should have a value and badgeTheme:

const rowData = [
  {
    id: 1,
    cells: {
      product: 'Premium Widget',
      categories: {
        tags: [
          { value: 'Featured', badgeTheme: 'primary' },
          { value: 'New', badgeTheme: 'secondary' }
        ]
      },
      price: '$49.99'
    }
  },
  {
    id: 2,
    cells: {
      product: 'Standard Widget',
      categories: {
        tags: [
          { value: 'Popular', badgeTheme: 'tertiary' }
        ]
      },
      price: '$29.99'
    }
  }
];

Complete Example

Here's a complete example showing how to set up a data table with badge columns that use multiple tags:

const productsTable = document.querySelector('q2-data-table');

const headerData = [
  { title: 'Product Name', key: 'name' },
  { title: 'Status', key: 'status', type: 'badge', align: 'center' },
  { title: 'Tags', key: 'tags', type: 'badge', align: 'center' },
  { title: 'Price', key: 'price', align: 'end' }
];

const rowData = [
  {
    id: 1,
    cells: {
      name: 'Premium Service',
      // Single badge example (traditional mode)
      status: {
        value: 'Active',
        badgeStatus: 'success',
        badgeTheme: 'primary'
      },
      // Multiple tags example
      tags: {
        tags: [
          { value: 'Featured', badgeTheme: 'primary' },
          { value: 'Best Seller', badgeTheme: 'secondary' },
          { value: 'New', badgeTheme: 'tertiary' }
        ]
      },
      price: '$99.99'
    }
  },
  {
    id: 2,
    cells: {
      name: 'Standard Service',
      status: {
        value: 'Pending',
        badgeStatus: 'warning',
        badgeTheme: 'secondary'
      },
      tags: {
        tags: [
          { value: 'Popular', badgeTheme: 'secondary' }
        ]
      },
      price: '$49.99'
    }
  }
];

productsTable.headers = headerData;
productsTable.rows = rowData;

Visual Behavior

The multiple tags feature includes the following visual characteristics:

• Tags display in a centered, flexible container that automatically wraps to multiple lines on smaller screens
• Consistent spacing between tags (both horizontally and vertically)
• Each tag can have its own independent theme color (primary, secondary, or tertiary)
• Empty tag arrays will not render any content in the cell

Slot Examples

While q2-data-table does a great job at displaying the data you need just by passing data into the component via properties, we understand that there will be times you want to customize the content. For this, we've exposed a series of dynamically named slots to allow you to do this.

In addition, by utilizing slots, you can further enhance your use of q2-data-table to provide expandable content or dropdowns to display a list of options for each row.

Header Slots: header-cell-<key>

With this slot, you can override the content of any header cell in the table. Using the header cell data from the Data Structure section above as reference, we use a dropdown as the "Day of Week" header.

<q2-data-table>
    <q2-dropdown slot="header-cell-day" label="Day of Week" type="icon" icon="options">
      <q2-dropdown-item value="Home">Home</q2-dropdown-item>
      <q2-dropdown-item value="Download as PDF">Download as PDF</q2-dropdown-item>
      <q2-dropdown-item value="Discombobulate">Discombobulate</q2-dropdown-item>
    </q2-dropdown>
</q2-data-table>

Cell Slots: row-<id>-cell-<key>

With this slot, you can override the content of any cell in any row of the table. Using the data from the Data Structure section above as a reference, we can replace the "Sales" cell on the row for "Thursday" with our own custom content:

<q2-data-table>
  <div slot="row-4-cell-sales">🤯 Lots</div>
</q2-data-table>

Dropdown cell: row-<id>-dropdown

One typical behavior is to have each row of a table contain a dropdown that presents actions to a user that they can take on that particular row of data. Due to the implementation of q2-dropdown and its intricacies, we are also exposing this as a slot. Again using the data from the Data Structure section, we can add a dropdown to the row for "Thursday" like this:

<q2-data-table>
  <q2-dropdown
    slot="row-4-dropdown"
    icon="options"
    alignment="right"
  >
    <q2-dropdown-item value="second">Report</q2-dropdown-item>
    <q2-dropdown-item value="third">Ask question</q2-dropdown-item>
  </q2-dropdown>
</q2-data-table>

Expandable Content Slot: row-<id>-expandable-content

Another common desire is to have a table row be clickable, where upon clicking, it expands to reveal more detailed content. Because this often requires complex HTML and Javascript to display the desired results, we expose it as a slot that you can optionally utilize. The following example adds expandable content to the "Thursday" row:

<q2-data-table>
  <div slot='row-4-expandable-content'>
    <h3>Thursday Was Great</h3>
    <p>But you already knew that.</p>
  </div>
</q2-data-table>

Empty Table Slot: empty-table

With this slot you can customize the look of your table's body when no row data is present. Alternatively, you may use the emptyIcon and emptyMessage properties to customize the empty state of the table with a q2-icon and custom text.

<q2-data-table>
  <div slot="empty-table" style="display: flex; justify-content: center; align-items: center; gap: 10px;">
    <q2-icon type="warning"></q2-icon>
    <b>Table has no row data.</b>
  </div>
</q2-data-table>

Sorting

By default, if a column has sortable: 'auto' set in the header data, the component will do its best to sort the data you provide in the rows property automatically. This works for most use cases you may have. However, a common use case is when you have multiple pages of content or need to provide a more detailed algorithm with which to sort your data.

For that, we recommend setting sortable: 'manual' in the desired header data, and listening to the sort event that is emitted from the component when you click on a sortable column header. Here is an example.

const dataTableElement = document.querySelector("q2-data-table")

function sortTransactions(event) {
  // Calling preventDefault() will tell the Data Table
  // NOT to perform the default sort functionality
  event.preventDefault();

  const {
    direction,
    header: { key },
  } = event.detail;

  dataTableElement.rows = [
    ...allTransactions.sort((a, b) => {
      if (direction === 'ASC') return a.cells[key] > b.cells[key] ? 1 : -1;
      else return a.cells[key] < b.cells[key] ? 1 : -1;
    }),
  ]);

  // You'll also want to update the headers to reflect which
  // column was sorted and it's direction
  dataTableElement.headers = allHeaders.map(header => (
    { ...header, sorted: header.key === key ? direction : undefined }))
  );
}

tableElement.current?.addEventListener('sort', sortTransactions);