TimesheetPivot

A horizontal pivot table for time tracking with heatmap coloring, column totals, and striped rows.

iOSAndroid

Preview TimesheetPivot on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-timesheet-pivot

Usage

import { TimesheetPivot } from '@/components/docyrus-native/timesheet-pivot';

const columns = [
  { key: 'mon', label: 'Mon' },
  { key: 'tue', label: 'Tue' },
  { key: 'wed', label: 'Wed' },
  { key: 'thu', label: 'Thu' },
  { key: 'fri', label: 'Fri' },
];

const rows = [
  {
    id: 'project-1',
    title: 'Project Atlas',
    subtitle: 'Mobile sprint',
    values: { mon: 2.5, tue: 1.5, wed: 4, thu: 3.5, fri: 2 },
  },
  {
    id: 'project-2',
    title: 'Project Northwind',
    values: { mon: 1, tue: 2, wed: 0, thu: 2.5, fri: 3 },
  },
];

<TimesheetPivot
  columns={columns}
  rows={rows}
  messages={{ row: 'Project' }}
  valueKind="hours"
  showTotals
/>

Features

Heatmap coloring — cells are tinted based on value intensity relative to the max value
Column totals footer — a summary row showing totals per column and a grand total
Striped rows — alternating row backgrounds for readability
FlatList rendering — virtualized row rendering with getItemLayout for O(1) scroll performance
Three value formats — raw, hours (2.5h), minutes (2h 30m)
Custom formatter — override cell display with valueFormatter
Row press — optional onRowPress callback for navigation
Dark mode — fully theme-aware with light/dark opacity adjustments

API Reference

TimesheetPivotProps

Prop	Type	Default	Description
`columns`	`TimesheetPivotColumn[]`	—	Column definitions (key + label)
`rows`	`TimesheetPivotRow[]`	—	Row data with values per column
`messages`	`Partial<TimesheetPivotMessages>`	—	App-supplied copy; each key wins over the translation provider
`isLoading`	`boolean`	`false`	Shows loading state
`emptyMessage`	`string`	—	Optional empty state override
`showTotals`	`boolean`	`true`	Shows total column per row + footer totals row
`emptyValue`	`string`	`'—'`	Placeholder for empty/zero cells
`valueKind`	`'raw' \| 'hours' \| 'minutes'`	`'raw'`	Default numeric formatter
`onRowPress`	`(row: TimesheetPivotRow) => void`	—	Row press callback
`valueFormatter`	`(value, columnKey, row) => string`	—	Custom cell value formatter
`className`	`string`	—	Additional wrapper className

TimesheetPivotColumn

Field	Type	Description
`key`	`string`	Unique column identifier (used as key in `values`)
`label`	`string`	Display label in header

TimesheetPivotRow

Field	Type	Description
`id`	`string`	Unique row identifier
`title`	`string`	Primary row label
`subtitle`	`string?`	Secondary label (shown below title)
`values`	`Record<string, CellValue>`	Cell values keyed by column key
`total`	`CellValue?`	Explicit total (auto-computed if omitted)

TimesheetPivotMessages

Every field is optional in the messages prop and falls back to <UiTranslationProvider>.

Field	Type	Fallback key	English fallback	Description
`loading`	`string`	`ui.timesheetPivot.loading`	`Loading timesheet...`	Loading state label
`empty`	`string`	`ui.timesheetPivot.empty`	`No time recorded`	Empty state label
`total`	`string`	`ui.timesheetPivot.total`	`Total`	Total column/row header label
`row`	`string`	`ui.timesheetPivot.row`	`Item`	First column header label

TimesheetPivotCellValue

type TimesheetPivotCellValue = number | string | null | undefined;

Value Formatting

The component supports three built-in formatters via valueKind:

Kind	Input	Output
`raw`	`2.5`	`2.5`
`hours`	`2.5`	`2.5h`
`minutes`	`150`	`2h 30m`

For custom formatting, use valueFormatter:

<TimesheetPivot
  valueFormatter={(value, columnKey, row) => {
    if (columnKey === '__total__') return `${value}h total`;
    return typeof value === 'number' ? `${value}h` : '—';
  }}
/>

Components

Component	Description
`TimesheetPivot`	Horizontal pivot table — the mobile timesheet view (conceptually the native counterpart of web `PivotCalendar`)

Type Exports

Type	Description
`TimesheetPivotProps`	Props for TimesheetPivot
`TimesheetPivotColumn`	`{ key, label }` column definition
`TimesheetPivotRow`	Row with per-column values
`TimesheetPivotCellValue`	`number \| string \| null \| undefined`
`TimesheetPivotValueKind`	`'raw' \| 'hours' \| 'minutes'`
`TimesheetPivotMessages`	Copy keys

TimesheetPivot

On this page