Skip to main content

Angular API Reference

Complete API documentation for @mindfiredigital/pivothead-angular.

Installation​

npm install @mindfiredigital/pivothead-angular

Component​

PivotHeadWrapperComponent​

The main Angular wrapper component for PivotHead.

import { PivotHeadWrapperComponent } from '@mindfiredigital/pivothead-angular';

Inputs​

data​

  • Type: PivotDataRecord[]
  • Default: undefined
  • Description: Array of data objects to process in the pivot table
salesData: PivotDataRecord[] = [
  { country: 'USA', category: 'Electronics', sales: 1500 },
  { country: 'Canada', category: 'Cars', sales: 1800 },
];
<pivot-head-wrapper [data]="salesData" />

options​

  • Type: PivotOptions
  • Default: undefined
  • Description: Pivot configuration including rows, columns, and measures
options: PivotOptions = {
  rows: [{ uniqueName: 'country', caption: 'Country' }],
  columns: [{ uniqueName: 'category', caption: 'Category' }],
  measures: [
    { uniqueName: 'sales', caption: 'Total Sales', aggregation: 'sum' },
  ],
};
<pivot-head-wrapper [data]="salesData" [options]="options" />

PivotOptions Interface:

interface PivotOptions {
  rows?: Dimension[];
  columns?: Dimension[];
  measures?: MeasureConfig[];
}

interface Dimension {
  uniqueName: string;
  caption: string;
}

interface MeasureConfig {
  uniqueName: string;
  caption: string;
  aggregation: AggregationType;
  format?: FormatOptions;
}

type AggregationType = 'sum' | 'avg' | 'count' | 'min' | 'max';

filters​

  • Type: FilterConfig[]
  • Default: undefined
  • Description: Array of filter configurations to apply to the data
filters: FilterConfig[] = [
  {
    field: 'country',
    operator: 'equals',
    value: 'USA'
  }
];
<pivot-head-wrapper [data]="salesData" [filters]="filters" />

pagination​

  • Type: PaginationConfig
  • Default: undefined
  • Description: Pagination settings for the pivot table
paginationConfig: PaginationConfig = {
  pageSize: 10,
  currentPage: 1,
};
<pivot-head-wrapper [data]="salesData" [pagination]="paginationConfig" />

PaginationConfig Interface:

interface PaginationConfig {
  pageSize: number;
  currentPage: number;
}

mode​

  • Type: 'default' | 'minimal' | 'none'
  • Default: 'default'
  • Description: Rendering mode for the pivot table
<!-- Default mode: Full UI -->
<pivot-head-wrapper [mode]="'default'" [data]="salesData" />

<!-- Minimal mode: Slot-based custom UI -->
<pivot-head-wrapper [mode]="'minimal'" [data]="salesData">
  <div slot="header">Custom Header</div>
  <div slot="body">Custom Body</div>
</pivot-head-wrapper>

<!-- None mode: Headless, no UI -->
<pivot-head-wrapper [mode]="'none'" [data]="salesData" />

Outputs​

stateChange​

  • Type: EventEmitter<PivotTableState>
  • Description: Emitted when the pivot table state changes (data, configuration, view mode, etc.)
onStateChange(event: PivotTableState) {
  console.log('State changed:', event);
  console.log('Data:', event.data);
  console.log('View mode:', event.viewMode);
}
<pivot-head-wrapper [data]="salesData" (stateChange)="onStateChange($event)" />

PivotTableState Interface:

interface PivotTableState<T = PivotDataRecord> {
  data: T[];
  viewMode: 'raw' | 'processed';
  filters?: FilterConfig[];
  pagination?: PaginationConfig;
  options?: PivotOptions;
}

viewModeChange​

  • Type: EventEmitter<{ mode: 'raw' | 'processed' }>
  • Description: Emitted when the view mode switches between raw and processed data
onViewModeChange(event: { mode: 'raw' | 'processed' }) {
  console.log('View mode changed to:', event.mode);
}
<pivot-head-wrapper
  [data]="salesData"
  (viewModeChange)="onViewModeChange($event)"
/>

paginationChange​

  • Type: EventEmitter<PaginationConfig>
  • Description: Emitted when pagination settings change
onPaginationChange(event: PaginationConfig) {
  console.log('Page:', event.currentPage);
  console.log('Page size:', event.pageSize);
}
<pivot-head-wrapper
  [data]="salesData"
  (paginationChange)="onPaginationChange($event)"
/>

dataLoaded​

  • Type: EventEmitter<{ recordCount: number, fileSize?: number }>
  • Description: Emitted when data is successfully loaded (via file import or URL)
onDataLoaded(event: { recordCount: number, fileSize?: number }) {
  console.log('Loaded', event.recordCount, 'records');
  if (event.fileSize) {
    console.log('File size:', event.fileSize, 'bytes');
  }
}
<pivot-head-wrapper (dataLoaded)="onDataLoaded($event)" />

error​

  • Type: EventEmitter<{ message: string, code?: string }>
  • Description: Emitted when an error occurs during data loading or processing
onError(event: { message: string, code?: string }) {
  console.error('Error:', event.message);
  if (event.code) {
    console.error('Error code:', event.code);
  }
}
<pivot-head-wrapper (error)="onError($event)" />

Public Methods​

Access these methods via ViewChild reference:

@ViewChild('pivotTable') pivotTable!: PivotHeadWrapperComponent;

State Management​

getState()​

Get the current pivot table state.

getState(): PivotTableState | undefined

Example:

const state = this.pivotTable.getState();
console.log('Current state:', state);

refresh()​

Refresh the pivot table, re-processing the current data.

refresh(): void

Example:

this.pivotTable.refresh();

reset()​

Reset the pivot table to its initial state.

reset(): void

Example:

this.pivotTable.reset();

Data Operations​

getData()​

Get the raw input data.

getData(): PivotDataRecord[] | undefined

Example:

const data = this.pivotTable.getData();
console.log('Raw data:', data);

getProcessedData()​

Get the processed pivot data.

getProcessedData(): unknown | undefined

Example:

const processed = this.pivotTable.getProcessedData();
console.log('Processed data:', processed);

getRawData()​

Alias for getData() - get the raw input data.

getRawData(): PivotDataRecord[] | undefined

Example:

const rawData = this.pivotTable.getRawData();

Sorting & Filtering​

sort()​

Sort data by a specific field.

sort(field: string, direction: 'asc' | 'desc'): void

Parameters:

  • field: The field name to sort by
  • direction: Sort direction ('asc' or 'desc')

Example:

this.pivotTable.sort('sales', 'desc');

getFilters()​

Get current filter configurations.

getFilters(): FilterConfig[] | undefined

Example:

const filters = this.pivotTable.getFilters();
console.log('Active filters:', filters);

Configuration​

setMeasures()​

Update the measures configuration.

setMeasures(measures: MeasureConfig[]): void

Example:

this.pivotTable.setMeasures([
  { uniqueName: 'sales', caption: 'Total Sales', aggregation: 'sum' },
  { uniqueName: 'profit', caption: 'Total Profit', aggregation: 'sum' },
]);

setDimensions()​

Update the dimensions (rows and columns).

setDimensions(dimensions: Dimension[]): void

Example:

this.pivotTable.setDimensions([
  { uniqueName: 'country', caption: 'Country' },
  { uniqueName: 'category', caption: 'Category' },
]);

setGroupConfig()​

Set or clear group configuration.

setGroupConfig(config: GroupConfig | null): void

Example:

this.pivotTable.setGroupConfig({
  field: 'category',
  order: 'asc',
});

// Clear grouping
this.pivotTable.setGroupConfig(null);

Pagination​

getPagination()​

Get current pagination configuration.

getPagination(): PaginationConfig | undefined

Example:

const pagination = this.pivotTable.getPagination();
console.log('Current page:', pagination?.currentPage);

setPageSize()​

Set the number of items per page.

setPageSize(size: number): void

Example:

this.pivotTable.setPageSize(25);

goToPage()​

Navigate to a specific page.

goToPage(page: number): void

Example:

this.pivotTable.goToPage(3);

previousPage()​

Navigate to the previous page.

previousPage(): void

Example:

this.pivotTable.previousPage();

nextPage()​

Navigate to the next page.

nextPage(): void

Example:

this.pivotTable.nextPage();

View Control​

setViewMode()​

Switch between raw and processed data view.

setViewMode(mode: 'raw' | 'processed'): void

Example:

this.pivotTable.setViewMode('raw');

getViewMode()​

Get the current view mode.

getViewMode(): 'raw' | 'processed' | undefined

Example:

const mode = this.pivotTable.getViewMode();
console.log('Current view mode:', mode);

Formatting​

formatValue()​

Format a value for display based on field configuration.

formatValue(value: unknown, field: string): string | undefined

Example:

const formatted = this.pivotTable.formatValue(1234.56, 'sales');
console.log(formatted); // "$1,234.56"

updateFieldFormatting()​

Update formatting options for a specific field.

updateFieldFormatting(field: string, format: FormatOptions): void

FormatOptions Interface:

interface FormatOptions {
  type?: 'number' | 'currency' | 'percentage' | 'date';
  decimals?: number;
  currencySymbol?: string;
  thousandsSeparator?: boolean;
  dateFormat?: string;
}

Example:

this.pivotTable.updateFieldFormatting('sales', {
  type: 'currency',
  decimals: 2,
  currencySymbol: '$',
  thousandsSeparator: true,
});

getFieldAlignment()​

Get the alignment setting for a field.

getFieldAlignment(field: string): string | undefined

Example:

const alignment = this.pivotTable.getFieldAlignment('sales');
console.log(alignment); // 'right'

showFormatPopup()​

Show the formatting configuration popup (default mode only).

showFormatPopup(): void

Example:

this.pivotTable.showFormatPopup();

Export​

exportToHTML()​

Export the pivot table to HTML format.

exportToHTML(fileName?: string): void

Example:

this.pivotTable.exportToHTML('sales-report');

exportToPDF()​

Export the pivot table to PDF format.

exportToPDF(fileName?: string): void

Example:

this.pivotTable.exportToPDF('sales-report');

exportToExcel()​

Export the pivot table to Excel format.

exportToExcel(fileName?: string): void

Example:

this.pivotTable.exportToExcel('sales-report');

openPrintDialog()​

Open the browser print dialog for the pivot table.

openPrintDialog(): void

Example:

this.pivotTable.openPrintDialog();

Drag & Drop​

swapRows()​

Swap two rows by index.

swapRows(from: number, to: number): void

Example:

this.pivotTable.swapRows(0, 2);

swapColumns()​

Swap two columns by index.

swapColumns(from: number, to: number): void

Example:

this.pivotTable.swapColumns(1, 3);

dragRow()​

Programmatically drag a row from one position to another.

dragRow(fromIndex: number, toIndex: number): void

Example:

this.pivotTable.dragRow(0, 3);

dragColumn()​

Programmatically drag a column from one position to another.

dragColumn(fromIndex: number, toIndex: number): void

Example:

this.pivotTable.dragColumn(1, 2);

setDragAndDropEnabled()​

Enable or disable drag and drop functionality.

setDragAndDropEnabled(enabled: boolean): void

Example:

this.pivotTable.setDragAndDropEnabled(true);

isDragAndDropEnabled()​

Check if drag and drop is currently enabled.

isDragAndDropEnabled(): boolean | undefined

Example:

const isEnabled = this.pivotTable.isDragAndDropEnabled();
console.log('Drag & drop enabled:', isEnabled);

File Import​

loadFromFile()​

Load data from a File object.

loadFromFile(file: File): Promise<void>

Example:

async handleFileUpload(event: Event) {
  const input = event.target as HTMLInputElement;
  const file = input.files?.[0];

  if (file) {
    await this.pivotTable.loadFromFile(file);
  }
}

loadFromUrl()​

Load data from a remote URL.

loadFromUrl(url: string): Promise<void>

Example:

await this.pivotTable.loadFromUrl('https://example.com/data/sales.csv');

connectToLocalCSV()​

Open file dialog and import a CSV file with full configuration options.

connectToLocalCSV(options?: ConnectionOptions): Promise<FileConnectionResult | undefined>

Example:

const result = await this.pivotTable.connectToLocalCSV({
  csv: {
    delimiter: ',',
    hasHeader: true,
    skipEmptyLines: true,
    trimValues: true,
  },
  maxFileSize: 1024 * 1024 * 1024, // 1GB
  useWorkers: true,
  workerCount: 4,
  chunkSizeBytes: 1024 * 1024 * 10, // 10MB chunks
});

console.log('Import result:', result);

connectToLocalJSON()​

Open file dialog and import a JSON file.

connectToLocalJSON(options?: ConnectionOptions): Promise<FileConnectionResult | undefined>

Example:

const result = await this.pivotTable.connectToLocalJSON({
  json: {
    validateSchema: true,
  },
  maxFileSize: 1024 * 1024 * 1024, // 1GB
  useWorkers: true,
  workerCount: 4,
});

connectToLocalFile()​

Open file dialog and import any supported file type (CSV or JSON).

connectToLocalFile(options?: ConnectionOptions): Promise<FileConnectionResult | undefined>

Example:

const result = await this.pivotTable.connectToLocalFile({
  csv: {
    delimiter: ',',
    hasHeader: true,
  },
  json: {
    validateSchema: true,
  },
  maxFileSize: 1024 * 1024 * 1024, // 1GB
  useWorkers: true,
  workerCount: 4,
  chunkSizeBytes: 1024 * 1024 * 10,
  onProgress: progress => {
    console.log(`Import progress: ${progress}%`);
  },
});

ConnectionOptions Interface:

interface ConnectionOptions {
  // CSV-specific options
  csv?: CSVParseOptions;

  // JSON-specific options
  json?: JSONParseOptions;

  // General options
  maxFileSize?: number;
  maxRecords?: number;
  onProgress?: (progress: number) => void;

  // Performance options
  useWorkers?: boolean;
  workerCount?: number;
  chunkSizeBytes?: number;
}

interface CSVParseOptions {
  delimiter?: string;
  hasHeader?: boolean;
  skipEmptyLines?: boolean;
  trimValues?: boolean;
  encoding?: string;
}

interface JSONParseOptions {
  validateSchema?: boolean;
}

FileConnectionResult Interface:

interface FileConnectionResult {
  success: boolean;
  recordCount?: number;
  fileSize?: number;
  fileName?: string;
  parseTime?: number;
  performanceMode?: 'wasm' | 'workers' | 'sync';
  error?: string;
}

Field Introspection​

getAvailableFields()​

Get information about all available fields in the dataset.

getAvailableFields(): FieldInfo[] | undefined

Example:

const fields = this.pivotTable.getAvailableFields();
console.log('Available fields:', fields);

FieldInfo Interface:

interface FieldInfo {
  name: string;
  caption: string;
  type: 'string' | 'number' | 'date' | 'boolean';
}

getSupportedAggregations()​

Get list of supported aggregation types.

getSupportedAggregations(): AggregationType[] | undefined

Example:

const aggregations = this.pivotTable.getSupportedAggregations();
console.log('Supported aggregations:', aggregations);
// ['sum', 'avg', 'count', 'min', 'max']

setMeasureAggregation()​

Change the aggregation type for a specific measure.

setMeasureAggregation(field: string, aggregation: AggregationType): void

Example:

this.pivotTable.setMeasureAggregation('sales', 'avg');

buildLayout()​

Build a pivot layout from a field selection.

buildLayout(selection: LayoutSelection): void

LayoutSelection Interface:

interface LayoutSelection {
  rows: string[];
  columns: string[];
  measures: Array<{
    field: string;
    aggregation: AggregationType;
  }>;
}

Example:

this.pivotTable.buildLayout({
  rows: ['country', 'region'],
  columns: ['category'],
  measures: [
    { field: 'sales', aggregation: 'sum' },
    { field: 'profit', aggregation: 'avg' },
  ],
});

Grouping​

getGroupedData()​

Get data grouped according to the current configuration.

getGroupedData(): Group[] | undefined

Example:

const grouped = this.pivotTable.getGroupedData();
console.log('Grouped data:', grouped);

Type Exports​

All TypeScript types are exported from the package:

import type {
  // Core Types
  PivotHeadElement,
  PivotOptions,
  PivotDataRecord,
  PivotTableState,

  // Configuration Types
  FilterConfig,
  PaginationConfig,
  MeasureConfig,
  Dimension,
  GroupConfig,
  FormatOptions,

  // File Import Types
  ConnectionOptions,
  FileConnectionResult,
  CSVParseOptions,
  JSONParseOptions,

  // Field Types
  FieldInfo,
  LayoutSelection,

  // Enums
  AggregationType,

  // Data Types
  Group,
} from '@mindfiredigital/pivothead-angular';

Complete Example​

import { Component, ViewChild, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { PivotHeadWrapperComponent } from '@mindfiredigital/pivothead-angular';
import type {
  PivotOptions,
  PivotDataRecord,
  PivotTableState,
  ConnectionOptions,
  FileConnectionResult,
} from '@mindfiredigital/pivothead-angular';

@Component({
  selector: 'app-complete-example',
  standalone: true,
  imports: [CommonModule, PivotHeadWrapperComponent],
  template: `
    <div>
      <div class="controls">
        <button (click)="importCSV()">Import CSV</button>
        <button (click)="exportExcel()">Export Excel</button>
        <button (click)="refresh()">Refresh</button>
        <button (click)="reset()">Reset</button>
      </div>

      <pivot-head-wrapper
        #pivotTable
        [mode]="'default'"
        [data]="salesData"
        [options]="options"
        [pagination]="paginationConfig"
        (stateChange)="onStateChange($event)"
        (dataLoaded)="onDataLoaded($event)"
        (error)="onError($event)"
      />

      @if (importResult) {
        <div class="result">
          <h3>Last Import</h3>
          <p>Records: {{ importResult.recordCount?.toLocaleString() }}</p>
          <p>Performance: {{ importResult.performanceMode }}</p>
          <p>Time: {{ importResult.parseTime }}ms</p>
        </div>
      }
    </div>
  `,
})
export class CompleteExampleComponent implements OnInit {
  @ViewChild('pivotTable') pivotTable!: PivotHeadWrapperComponent;

  salesData: PivotDataRecord[] = [
    { country: 'USA', category: 'Electronics', sales: 1500, profit: 300 },
    { country: 'Canada', category: 'Cars', sales: 1800, profit: 450 },
    { country: 'Australia', category: 'Accessories', sales: 1200, profit: 240 },
  ];

  options: PivotOptions = {
    rows: [{ uniqueName: 'country', caption: 'Country' }],
    columns: [{ uniqueName: 'category', caption: 'Category' }],
    measures: [
      { uniqueName: 'sales', caption: 'Total Sales', aggregation: 'sum' },
      { uniqueName: 'profit', caption: 'Total Profit', aggregation: 'sum' },
    ],
  };

  paginationConfig = {
    pageSize: 10,
    currentPage: 1,
  };

  importResult: FileConnectionResult | null = null;

  ngOnInit() {
    console.log('Component initialized');
  }

  async importCSV() {
    const options: ConnectionOptions = {
      csv: {
        delimiter: ',',
        hasHeader: true,
        skipEmptyLines: true,
        trimValues: true,
      },
      maxFileSize: 1024 * 1024 * 1024, // 1GB
      useWorkers: true,
      workerCount: 4,
      chunkSizeBytes: 1024 * 1024 * 10,
    };

    try {
      const result = await this.pivotTable.connectToLocalCSV(options);
      this.importResult = result || null;
    } catch (error: any) {
      console.error('Import error:', error);
    }
  }

  exportExcel() {
    this.pivotTable.exportToExcel('sales-report');
  }

  refresh() {
    this.pivotTable.refresh();
  }

  reset() {
    this.pivotTable.reset();
  }

  onStateChange(state: PivotTableState) {
    console.log('State changed:', state);
  }

  onDataLoaded(event: { recordCount: number; fileSize?: number }) {
    console.log('Data loaded:', event.recordCount, 'records');
  }

  onError(event: { message: string; code?: string }) {
    console.error('Error:', event.message);
  }
}

See Also​