Column Helpers

Column helpers reduce boilerplate in table column definitions by providing common rendering patterns. They are shared between AdminListTableBlock and ListTableBlock for consistent column behavior.

columnHelpers.text('name', 'Name', { sortable: true })

columnHelpers.primary('name', 'Project Name', {
  descriptionKey: 'description',
  sortable: true,
})

columnHelpers.badge('status', 'Status', {
  active: 'success',
  pending: 'warning',
  archived: 'secondary',
})

// Relative (default)
columnHelpers.date('createdAt', 'Created', { sortable: true })

// Absolute with time
columnHelpers.date('createdAt', 'Created', { style: 'absolute', includeTime: true })

columnHelpers.number('count', 'Count')  // 1.2K, 45.7K (compact by default)
columnHelpers.number('id', 'ID', { compact: false })  // 1,234 (full number)
columnHelpers.number('score', 'Score', { decimals: 1 })  // 1234.0 (decimals disables compact)

Currency display with integer format and full value tooltip. Footer aggregations formatted as currency.

columnHelpers.currency('amount', 'Budget')
columnHelpers.currency('amount', 'Budget (EUR)', { currency: 'EUR' })

Percentage display with integer format and full value tooltip.

columnHelpers.percentage('progress', 'Progress')
columnHelpers.percentage('progress', 'Completion', { decimals: 1 })

Checkmark/dash indicators for true/false values. Supports editable mode with toggle switch.

columnHelpers.boolean('isActive', 'Active')

User profile with avatar and name. Supports click handler for opening UserSheet.

columnHelpers.user('creator', 'Created By', {
  onClick: (user) => openUserSheet(user.id),
})

Displays a mini trend chart within the table cell. Perfect for showing historical trends alongside other data. Uses SparklineChart under the hood.

columnHelpers.sparkline('trend', '7-Day Trend', {
  data: (item) => item.dailyResponses,
  width: 80,
  height: 24,
  showArea: true,
  showEndDot: false,
  color: 'var(--chart-2)',
  hideOnMobile: true,
})

Displays star ratings (0-5) with support for half-stars. Optionally shows response count after the stars. Can be made interactive with the editable option for inline rating changes.

// With response count
columnHelpers.starRating('satisfaction', 'Satisfaction', {
  rating: (item) => item.averageRating,
  count: (item) => item.totalResponses,
})

// Rating only (no count)
columnHelpers.starRating('satisfaction', 'Rating', {
  rating: (item) => item.averageRating,
})

// Interactive (editable)
columnHelpers.starRating('userRating', 'Your Rating', {
  rating: (item) => item.userRating,
  editable: { canEdit: (item) => !item.locked },
})

Displays 1-3 compact KPI values as colored badges. Each badge can have its own color variant (success, warning, destructive, info, muted) and optional tooltip. Perfect for showing multiple metrics in a single column.

columnHelpers.kpiSummary('metrics', 'Metrics', {
  badgeWidth: 'lg',  // 'sm' (40px) | 'md' (48px) | 'lg' (56px) - uniform width
  values: (item) => [
    { value: item.healthGrade, variant: 'success', tooltip: 'Health' },
    { value: `${item.min}-${item.max}`, variant: 'info', tooltip: 'Range' },
    { value: `${item.impact}%`, variant: item.impact > 20 ? 'success' : 'muted' },
  ],
})

Displays a row of dots where filled dots indicate the rating level. Supports custom max dots (up to 10) and color options. Can be made interactive for quick inline value changes.

// Basic dot rating
columnHelpers.dotRating('priority', 'Priority', {
  value: (item) => item.priorityLevel,
  maxDots: 5,
})

// Custom color
columnHelpers.dotRating('urgency', 'Urgency', {
  value: (item) => item.urgencyLevel,
  maxDots: 3,
  color: 'destructive', // 'primary' | 'success' | 'warning' | 'destructive'
})

// Interactive (editable)
columnHelpers.dotRating('priority', 'Priority', {
  value: (item) => item.priorityLevel,
  maxDots: 5,
  editable: { canEdit: (item) => !item.locked },
})

Combine ratingBar and scoreBadge to build survey question matrices. The ratingBar shows response distribution with color-coded bars (red=low, green=high), while scoreBadge displays the average score with color coding. Generate columns dynamically for any rating scale (1-5, 0-10, etc.).

// Build survey matrix with dynamic rating columns
const getMaxCount = (item) => Math.max(...item.responses.map(r => r.count));

const columns = [
  columnHelpers.text('question', 'Question'),
  // Generate columns for each rating value
  ...[1, 2, 3, 4, 5].map((rating) =>
    columnHelpers.ratingBar(`rating${rating}`, String(rating), {
      count: (item) => item.responses.find(r => r.rating === rating)?.count ?? 0,
      maxCount: getMaxCount,
      rating,       // For color coding
      maxRating: 5, // Scale max
    })
  ),
  columnHelpers.scoreBadge('avgScore', 'Avg', {
    score: (item) => item.averageScore,
    maxScore: 5,
    decimals: 2,
    colorScale: 'diverging', // or 'sequential'
  }),
  columnHelpers.number('totalResponses', 'n'),
];

Displays audience access level with icon and label. Supports editable dropdown for inline level changes.

columnHelpers.audienceAccess('access', 'Access', {
  editable: true,
  onChange: (item, newLevel) => handleAccessChange(item.id, newLevel),
})

Displays clickable links with automatic hostname extraction, external link icons, and truncation. Full URL shown in tooltip on hover.

columnHelpers.link('website', 'Website', {
  maxLength: 30,
  showExternalIcon: true,
})

Displays email addresses as mailto links with optional copy button on hover. Truncates long emails with tooltip showing the full address.

columnHelpers.email('contactEmail', 'Contact', {
  showCopy: true,
  maxLength: 25,
})

Displays phone numbers as tel: links with automatic formatting. Copy button appears on hover for easy clipboard access.

columnHelpers.phone('phoneNumber', 'Phone', {
  format: true,
  showCopy: true,
})

Cover	Project	Status
	Alpha Project	active
	Beta Testing	pending
	Legacy Migration	archived

Displays image thumbnails with customizable size (sm/md/lg). Supports fallback images and optional hover-to-expand for larger preview.

columnHelpers.thumbnail('coverImage', 'Cover', {
  size: 'md',
  fallback: '/placeholder.png',
  expandOnHover: true,
})

Displays multiple tags as badges with configurable max visible count. Overflow shows "+N more" badge with tooltip listing remaining tags.

columnHelpers.tags('labels', 'Labels', {
  tags: (item) => item.tags, // string[] or TagItem[]
  maxVisible: 2,
  defaultVariant: 'secondary',
})

Displays code, IDs, or SKUs with monospace styling. Supports prefix (like # or v), copy button, and truncation for long values.

columnHelpers.code('sku', 'SKU', {
  prefix: '#',
  showCopy: true,
  uppercase: false,
})

Converts bytes to human-readable format (KB, MB, GB, etc.). Tooltip shows exact byte count. Supports different input units.

columnHelpers.fileSize('sizeBytes', 'Size', {
  inputUnit: 'bytes', // 'bytes' | 'kb' | 'mb'
  sortable: true,
})

Formats milliseconds (or other units) to human-readable duration. Supports short (1h 30m), long (1 hour 30 minutes), and compact (1:30:00) styles.

columnHelpers.duration('elapsedMs', 'Duration', {
  inputUnit: 'ms', // 'ms' | 'seconds' | 'minutes'
  style: 'short', // 'short' | 'long' | 'compact'
  maxUnits: 2,
})

Displays a colored dot indicator with optional text label. Supports pulse animation for "live" status indicators. Colors: success, warning, destructive, info, muted.

columnHelpers.statusDot('status', 'Status', {
  color: (item) => item.isOnline ? 'success' : 'muted',
  label: (item) => item.isOnline ? 'Online' : 'Offline',
  pulse: true,
})

Displays trend indicators with directional arrows. Green for positive, red for negative, muted for flat. Use invertColors for metrics where up is bad (costs).

columnHelpers.trend('growth', 'Growth', {
  value: (item) => item.growthPercent,
  isPercentage: true,
  invertColors: false, // true for costs
})

Displays health scores as colored grade badges. Supports letter grades (A+, B, C-) or numeric scores that map to grades automatically.

// Letter grade
columnHelpers.healthScore('grade', 'Health', {
  score: (item) => item.healthGrade,
  type: 'grade',
})

// Numeric (auto-converts to grade)
columnHelpers.healthScore('score', 'Health', {
  score: (item) => item.score,
  type: 'numeric',
  maxScore: 100,
})

Displays multiple user avatars in an overlapping stack. Shows "+N" overflow indicator when exceeding maxVisible. Tooltip shows all names.

columnHelpers.avatarStack('team', 'Team', {
  users: (item) => item.assignees,
  maxVisible: 3,
  size: 'sm', // 'sm' | 'md'
  onClick: (user) => openUserSheet(user.id),
})

Displays a mini horizontal progress bar with optional value label. Supports percentage, fraction, or number formats. Color can be static or dynamic.

columnHelpers.miniBar('progress', 'Progress', {
  value: (item) => item.completedTasks,
  maxValue: (item) => item.totalTasks,
  valueFormat: 'fraction', // 'percentage' | 'fraction' | 'number'
  color: 'primary', // or (value, max) => 'success' | 'warning' | etc.
})

Full control over rendering with custom render function.

columnHelpers.custom('actions', 'Actions', {
  render: (item) => <Button size="sm">View</Button>,
  align: 'right',
})