STable <s-table>

A table for structured data, with optional pagination, a loading state and a list layout on small screens. STable is the typed Vue 3 wrapper for Shopify's Polaris <s-table> web component.

import { STable } from 'polaris-vue-elements'

Best practices

• Use tables for data merchants compare. Tables fit many records that share the same attributes and need to be scanned side by side. For a simple list with nothing to compare, pick a simpler component.
• Plan for the mobile list layout. On mobile the table turns into a list, so check that your headers and values still read well as stacked label and value pairs rather than a grid.
• Keep the column count low. Many columns make a table hard to scan and force horizontal scrolling. Show only the columns merchants need for their task, and consider revealing the rest on demand.
• Write clear column headers. Keep each STableHeader short and descriptive so merchants know exactly what data the column holds.
• Plan for large datasets. Big tables hurt performance and usability. Turn on paginate once you have more than roughly 50 to 100 rows, or think about adding filters or search so merchants can get to the right records quicker.

<STable paginate hasNextPage>
  <STableHeaderRow>
    <STableHeader>Product</STableHeader>
    <STableHeader format="numeric">Inventory</STableHeader>
  </STableHeaderRow>
  <STableBody>
    <STableRow>
      <STableCell>Snowboard</STableCell>
      <STableCell>24</STableCell>
    </STableRow>
  </STableBody>
</STable>

See Shopify's best practices for <s-table> for the full guidance.

Example

OrderCustomerTotalStatus#1001Alex Morgan$120.00Fulfilled#1002Sam Rivera$45.50Pending#1003Jamie Lee$310.25Cancelled

<script setup>
import {
  STable,
  STableHeaderRow,
  STableHeader,
  STableBody,
  STableRow,
  STableCell,
  SBadge,
} from 'polaris-vue-elements'
</script>

<template>
  <!-- STable is the root: it lays out the header row + body and can switch to a
       "list" layout on narrow devices when variant="auto". -->
  <STable variant="auto">
    <STableHeaderRow>
      <STableHeader listSlot="primary">Order</STableHeader>
      <STableHeader listSlot="secondary">Customer</STableHeader>
      <STableHeader format="currency">Total</STableHeader>
      <STableHeader>Status</STableHeader>
    </STableHeaderRow>
    <STableBody>
      <STableRow>
        <STableCell>#1001</STableCell>
        <STableCell>Alex Morgan</STableCell>
        <STableCell>$120.00</STableCell>
        <STableCell><SBadge tone="success">Fulfilled</SBadge></STableCell>
      </STableRow>
      <STableRow>
        <STableCell>#1002</STableCell>
        <STableCell>Sam Rivera</STableCell>
        <STableCell>$45.50</STableCell>
        <STableCell><SBadge tone="warning">Pending</SBadge></STableCell>
      </STableRow>
      <STableRow>
        <STableCell>#1003</STableCell>
        <STableCell>Jamie Lee</STableCell>
        <STableCell>$310.25</STableCell>
        <STableCell><SBadge tone="critical">Cancelled</SBadge></STableCell>
      </STableRow>
    </STableBody>
  </STable>
</template>

Props

Prop	Type	Description
hasNextPage	boolean	Whether there's an additional page of data.
hasPreviousPage	boolean	Whether there's a previous page of data.
loading	boolean	Whether the table is in a loading state, such as initial page load or loading the next page in a paginated table. When true, the table could be in an inert state, which prevents user interaction.
paginate	boolean	Whether to use pagination controls.
variant	"auto" | "list"	The layout variant of the table component. - list: Always displays as a list layout. - auto: Automatically displays as a table on wide screens and as a list on narrow screens.

Events

Event	Type
nextpage	Event
previouspage	Event

Listen for these with @nextpage-style listeners on <STable>.

Slots

Slot	Description
default	The table structure displayed within the table component, including table headers, rows, and cells that organize data in a grid format.
filters	Additional filters to display in the table, such as search fields or other input components that allow users to narrow down the displayed data.