Skip to main content

Installation

npx @soft-ui/cli add table

Usage

import { Table } from '@soft-ui/react/table'

export default function Example() {
  return (
    <Table.Root size="m">
      <Table.Header>
        <Table.Row isHeader>
          <Table.Head>Name</Table.Head>
          <Table.Head>Status</Table.Head>
          <Table.Head>Role</Table.Head>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        <Table.Row>
          <Table.Cell>John Doe</Table.Cell>
          <Table.Cell>Active</Table.Cell>
          <Table.Cell>Admin</Table.Cell>
        </Table.Row>
      </Table.Body>
    </Table.Root>
  )
}

Examples

Sizes

Four sizes available: s, m (default), l, xl.
<Table.Root size="s">...</Table.Root>
<Table.Root size="m">...</Table.Root>
<Table.Root size="l">...</Table.Root>
<Table.Root size="xl">...</Table.Root>

Sortable Columns

Add sorting with sortDirection and onSort props.
const [sortColumn, setSortColumn] = useState<string | null>(null)
const [sortDirection, setSortDirection] = useState<'asc' | 'desc' | null>(null)

const handleSort = (column: string) => {
  if (sortColumn === column) {
    setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc')
  } else {
    setSortColumn(column)
    setSortDirection('asc')
  }
}

<Table.Head 
  sortDirection={sortColumn === 'name' ? sortDirection : null}
  onSort={() => handleSort('name')}
>
  Name
</Table.Head>

Row Selection

Use TableCheckboxCell for selectable rows.
const [selected, setSelected] = useState<string[]>([])

<Table.Row selected={selected.includes(row.id)}>
  <Table.CheckboxCell
    checked={selected.includes(row.id)}
    onCheckedChange={(checked) => {
      setSelected(checked 
        ? [...selected, row.id] 
        : selected.filter(id => id !== row.id)
      )
    }}
  />
  <Table.Cell>...</Table.Cell>
</Table.Row>

Specialized Cells

Text Cell

Display text with optional prefix, suffix, and additional info.
<Table.TextCell 
  prefix={<Table.Icon><RiUserLine /></Table.Icon>}
  additionalInfo="[email protected]"
  emphasized
>
  John Doe
</Table.TextCell>

Number Cell

Right-aligned cell for numeric data with tabular nums.
<Table.NumberCell>1,234.56</Table.NumberCell>

Badge Cell

Display status badges with consistent width.
<Table.BadgeCell variant="success" width="100px">
  Active
</Table.BadgeCell>

Avatar Group Cell

Show multiple user avatars.
<Table.AvatarGroupCell 
  avatars={[
    { src: '/avatar1.jpg', initials: 'JD' },
    { src: '/avatar2.jpg', initials: 'AS' },
  ]}
  max={3}
/>

Progress Cell

Display progress indicators.
<Table.ProgressCell value={75} tone="success" />

Actions Cell

Right-aligned actions with buttons.
<Table.ActionsCell>
  <Button variant="link-neutral" size="xs">Edit</Button>
  <IconButton variant="ghost" size="2xs">
    <RiMoreLine />
  </IconButton>
</Table.ActionsCell>

Fixed Layout

Use fixedLayout for tables with explicit column widths.
<Table.Root fixedLayout>
  <Table.Header>
    <Table.Row isHeader>
      <Table.Head style={{ width: '40%' }}>Name</Table.Head>
      <Table.Head style={{ width: '30%' }}>Status</Table.Head>
      <Table.Head style={{ width: '30%' }}>Role</Table.Head>
    </Table.Row>
  </Table.Header>
  ...
</Table.Root>

API Reference

Table.Root

size
string
default:"m"
Size of the table: s, m, l, xl. Affects row height and cell padding.
fixedLayout
boolean
default:false
Use CSS table-layout: fixed. Columns with explicit widths stay fixed.

Table.Header

Standard <thead> element with consistent border styling.

Table.Body

Standard <tbody> element. Standard <tfoot> element with background and border.

Table.Row

selected
boolean
default:false
Highlights row with background and left border indicator.
isHeader
boolean
default:false
When true, disables hover effects for header rows.

Table.Head

sortDirection
'asc' | 'desc' | null
Current sort direction. Shows sort icon when provided.
onSort
() => void
Click handler for sorting. Makes column sortable with interactive button.
align
string
default:"left"
Text alignment: left, right.

Table.Cell

Basic table cell. Use specialized cell components for common patterns.

Table.CheckboxCell

checked
boolean
Checkbox state.
onCheckedChange
(checked: boolean) => void
Callback when checkbox changes.
indeterminate
boolean
Show indeterminate state (for “select all” checkboxes).

Table.TextCell

children
ReactNode
Primary text content.
additionalInfo
string
Secondary text. Stacks below on large sizes, inline with dot separator on small.
prefix
ReactNode
Icon or element before text.
suffix
ReactNode
Icon or element after text.
emphasized
boolean
Use medium font weight for primary text.

Table.NumberCell

children
ReactNode
Numeric content. Automatically right-aligned with tabular nums.

Table.BadgeCell

variant
string
default:"neutral"
Badge variant.
isEmphasized
boolean
default:true
Badge emphasis.
align
string
default:"left"
Alignment: left, right.
width
string
Fixed width to prevent column resizing.

Table.AvatarGroupCell

avatars
Array<{ src?: string; initials?: string }>
Array of avatar data.
max
number
default:3
Maximum avatars to show before overflow.

Table.ProgressCell

value
number
Progress value (0-100).
tone
string
default:"default"
Progress tone: default, success, warning, danger.

Table.ActionsCell

children
ReactNode
Action buttons or custom content. Defaults to “View” link and more menu.

Table.Icon

tone
string
default:"default"
Icon color tone: default, success, warning, danger, info.

Table.Prefix

Context-aware prefix component (checkbox, icon, avatar) that adapts to table size.

Accessibility

  • Uses semantic HTML table elements
  • Sortable columns have proper aria-sort attributes
  • Checkbox cells are clickable with keyboard support
  • Row selection indicated with data-selected attribute
  • Focus management for interactive elements

Design Tokens

Table uses design tokens for consistent styling:
  • Spacing: --space-* for row heights, cell padding, gaps
  • Border radius: --radius-4, --radius-8, --radius-max
  • Colors: --color-border-*, --color-surface-*, --color-content-*, --color-actions-primary-default (selection indicator)
  • Typography: --font-size-*, --line-height-*, --font-weight-medium

Build docs developers (and LLMs) love