Generate Professional & Beautiful PDF Tables with jsPDF-Table

jspdf-table is a JavaScript/TypeScript library to render complex data sets into structured, customizable PDF tables using the jsPDF.js library.

The library helps you handle real-world table requirements such as text wrapping for long content, automatic column width calculations, and maintaining header visibility across page breaks.

It can be useful for generating reports, invoices, data exports, and any document that requires structured tabular data presentation.

Features:

• Column Control: Set fixed, percentage-based, or automatic column widths with min/max constraints.
• Styling Options: Comes with built-in themes and allows for deep customization of colors, fonts, and borders.
• Page Breaks: Automatically adds new pages when content overflows, repeating table headers for readability.
• Flexible Layouts: Multiple modes for calculating column widths, including auto, equal, and content.
• Error Handling: Provides specific error classes for validation and rendering issues.

How to use it:

1. Install both jspdf and jspdf-table packages with NPM:

# NPM
$ npm install jspdf @ikramrasheed/jspdf-table

2. Import them into your project.

import jsPDF from 'jspdf';
import { autoTable } from '@ikramrasheed/jspdf-table';

3. Or directly load the UMD versions in the document.

<script src="/path/to/cdn/jspdf.umd.min.js"></script>
<script src="/path/to/dist/index.umd.js"></script>

4. Initialize jsPDF, define your columns and tabular data, and then call the autoTable function.

const doc = new jsPDF();

// Define column headers and data keys
const columns = [
  { header: 'ID', dataKey: 'id', width: 50, align: 'center' },
  { header: 'Name', dataKey: 'name', minWidth: 80, align: 'left' },
  { header: 'Price', dataKey: 'price', align: 'right', headerAlign: 'center' },
  { header: 'Status', dataKey: 'status', width: '20%', align: 'center' }
]

// Provide the data as an array of objects
const data = [
  { id: 1, name: 'Laptop Computer', price: 1299.99, status: 'In Stock' },
  { id: 2, name: 'Mouse', price: 29.99, status: 'Low Stock' },
  { id: 3, name: 'Keyboard', price: 79.99, status: 'Out of Stock' },
  { id: 4, name: 'Monitor 27"', price: 349.99, status: 'In Stock' }
];


// Generate the table
const result = autoTable(doc, columns, data, {
  startY: 30,
  theme: 'grid',
  headerStyles: {
    fillColor: [52, 152, 219],
    textColor: [255, 255, 255],
    fontStyle: 'bold'
  }
});

5. Download the table as a PDF file.

doc.save('myTable.pdf');

6. Available options to customize the table.

• startY: The vertical starting position (Y-coordinate) for the table on the page.
• margin: Sets the page margins. You can provide a single number for all sides or an object like { top, right, bottom, left }.
• pageBreak: Controls page break behavior. 'auto' (the default) adds a new page when content overflows, 'avoid' attempts to keep the table on a single page, and 'always' forces a page break before rendering the table.
• theme: Applies a pre-defined visual style to the table. The available options are 'striped', 'grid', 'plain', and 'minimal'.
• tableWidth: Defines the total width of the table. This can be a specific number, a percentage of the available page width (e.g., '80%'), or 'auto'.
• columnWidthMode: Determines the strategy for calculating column widths. 'auto' respects individual column settings, 'fixed' requires all widths to be explicitly set, 'content' sizes columns based on their content, and 'equal' distributes the available width evenly among columns.
• showHeader: A boolean (true or false) to control the visibility of the table header.
• showBorders: A boolean that toggles the visibility of all cell borders.
• alternateRowColors: A boolean that, when true, applies the alternateRowStyles to every other row.
• styles: An object containing default styles applied to every cell in the table, such as fontSize, cellPadding, and font.
• headerStyles: An object with styles that apply only to the header cells, overriding the default styles.
• bodyStyles: An object with styles that apply only to the body cells, overriding the default styles.
• alternateRowStyles: An object defining the styles for alternating rows when alternateRowColors is enabled.
• borderStyles: An object to configure the thickness of different borders, with keys like top, bottom, horizontal, and vertical.
• rowHeight: Sets a fixed height for each body row or can be set to 'auto' to calculate height based on the cell content.
• headerHeight: Sets a fixed height for the header row or can be set to 'auto' to calculate its height based on content.

const result = autoTable(doc, columns, data, {
  startY?: number;
  margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
  pageBreak?: 'auto' | 'avoid' | 'always';
  theme?: 'striped' | 'grid' | 'plain' | 'minimal';
  tableWidth?: number | 'auto' | string; // Fixed width, auto-fit, or percentage
  columnWidthMode?: 'auto' | 'fixed' | 'content' | 'equal';
  showHeader?: boolean;
  showBorders?: boolean;
  alternateRowColors?: boolean;
  styles?: CellStyles;
  headerStyles?: CellStyles & ColorStyles;
  bodyStyles?: CellStyles & ColorStyles;
  alternateRowStyles?: CellStyles & ColorStyles;
  borderStyles?: BorderStyles;
  rowHeight?: number | 'auto';
  headerHeight?: number | 'auto';
});

7. All Column configs:

• header: The text to display in the column’s header cell. This is a required property.
• dataKey: The key used to retrieve the corresponding value from each object in your data array. This is also required.
• width: Sets the column’s width. You can use a fixed number (e.g., 100), a percentage string (e.g., '30%'), or 'auto' to let the library decide.
• align: Defines the horizontal alignment for the content in the body cells. The options are 'left', 'center', or 'right'.
• headerAlign: Sets the horizontal alignment specifically for the header text. If you don’t set this, it will use the value from the align property.
• minWidth: A number that specifies the minimum width the column can shrink to, which is useful for automatic width calculations.
• maxWidth: A number that specifies the maximum width the column can expand to. This is particularly helpful when using wrap to control how wide a column gets.
• wrap: A boolean (true or false) that determines if long text within a cell should wrap to multiple lines. This requires a width or maxWidth to be set.

const columns = [
  { 
    header: string;
    dataKey: string;
    width?: number | 'auto' | string; // Fixed width, auto-calculate, or percentage
    align?: 'left' | 'center' | 'right';
    headerAlign?: 'left' | 'center' | 'right';
    minWidth?: number;
    maxWidth?: number;
    wrap?: boolean;
  },
  // ...
]

8. Here are the values returned by the autoTable function.

• finalY: A number representing the final Y-coordinate on the page after the last row of the table has been rendered. This is extremely useful for positioning subsequent content directly below the table.
• tableWidth: The actual calculated width of the entire table in the document’s units.
• tableHeight: The total height of the table, including all its rows and the header, summed across all pages it spans.
• pageCount: The total number of pages the table occupies. This will be 1 for tables that fit on a single page and more for tables that trigger page breaks.

9. One aspect we appreciate is the library’s specific error handling. Instead of throwing generic errors, it provides distinct error classes that help you pinpoint the problem quickly. This is useful in complex applications where table data or options are generated dynamically.

import { ValidationError, RenderError } from '@ikramrasheed/jspdf-table';
try {
  // Your autoTable call here
  autoTable(doc, columns, data, options);
} catch (error) {
  if (error instanceof ValidationError) {
    // This catches issues with your input configuration.
    console.error('Invalid input:', error.message);
  } else if (error instanceof RenderError) {
    // This catches problems during the PDF drawing process.
    console.error('Rendering failed:', error.message);
  } else {
    // Catch any other unexpected errors.
    console.error('An unexpected error occurred:', error);
  }
}

• ValidationError: You’ll see this if there’s a problem with your columns or options objects. For example, forgetting to provide a dataKey for a column or passing an invalid value for the theme option will throw this error. It helps you catch configuration mistakes before the rendering even begins.
• RenderError: This error occurs when an issue arises during the actual PDF generation phase. While less common, it could happen if internal calculation issues or problems are interacting with the jsPDF document instance.

FAQs

Q: How do I add content after the table?
A: The autoTable function returns an object containing finalY. This value is the Y-coordinate right below the last row of the table. Use it as the starting Y for your next element, like doc.text('This comes after the table', 20, result.finalY + 10);.

Q: Can I use custom fonts in the table?
A: Yes. You first need to load the custom font into your jsPDF instance. Once the font is registered in the document, you can specify it by name in any of the style objects, for example: styles: { font: 'MyCustomFont' }.

Q: What happens if my table is wider than the page?
A: The library will attempt to render the table at the specified tableWidth (which defaults to the page width minus margins). If your column widths exceed this, the content may be clipped or overlap. It’s your responsibility to ensure your column width, minWidth, and maxWidth properties are set appropriately to fit within the page boundaries. The library manages vertical overflow (page breaks), not horizontal.

Q: How is jspdf-table different from jspdf-autotable?
A: While both serve a similar purpose, jspdf-table is a newer library written in TypeScript, offering strong typing out of the box. jspdf-autotable is more established and has a larger community.

The post Generate Professional & Beautiful PDF Tables with jsPDF-Table appeared first on CSS Script.