Documentation
Type Aliases
Cell
Ƭ Cell: ImageCell | TextCell | ChartCell | TextTemplateCell
Defined in
CellOptions
Ƭ CellOptions: Object
Type declaration
| Name | Type | Description |
|---|---|---|
columnSpan? | number | Sets how many columns within a row a cell will span. Default is 1. |
horizontalAlign? | HorizontalAlignment | Sets the horizontal alignment of a cell’s contents within the table row. Default is “center”. |
verticalAlign? | VerticalAlignment | Sets the vertical alignment of a cell’s contents within the table row. Default is “center”. |
Defined in
CellStyle
Ƭ CellStyle: Object
Type declaration
| Name | Type | Description |
|---|---|---|
backgroundColor? | string | Sets the background color of the cell (example: “yellow” or “#e6e6e6”). |
bottomBorder? | boolean | Adds a bottom border to the cell |
grid? | boolean | Adds a border around the cell. |
gridColor? | string | Sets the color of the grid borders. Default is black. |
lineGap? | number | Sets the line spacing around the cell contents. |
noWrap? | boolean | Prevents a text from wrapping within a cell. If true, adds an ellipsis (“…”) at the end of the text if cutoff. |
Defined in
CellValue
Ƭ CellValue: string | number
Defined in
ColumnSetting
Ƭ ColumnSetting: Object
Sets optional column settings for table rows.
Type declaration
| Name | Type | Description |
|---|---|---|
align? | HorizontalAlignment | Sets the horizontal alignment of the contents in each column. Default is “center”. |
splitFn? | ColumnSplitFn | Note: Setting a splitFn on a column containing an image will throw an error. |
width? | ColumnWidth | - |
Defined in
ColumnSplitFn
Ƭ ColumnSplitFn: (value: string, measure: (text: string) => VerticalMeasure, availableSpace: number) => [string, string] | [string]
If your table has data columns that can be of variable height, such as a notes column that may have very long text, and the height of the row exceeds the available page height, the table will be split with the row added to the next page. Sometimes you may not want that behavior, and prefer the row itself to be split. Use the splitFn property on a column to cleanly break the text and continue it on the next page. You can import splitColumn to accomplish this, or use your own custom split function.
Type declaration
▸ (value, measure, availableSpace): [string, string] | [string]
Parameters
| Name | Type |
|---|---|
value | string |
measure | (text: string) => VerticalMeasure |
availableSpace | number |
Returns
[string, string] | [string]
Defined in
ColumnWidth
Ƭ ColumnWidth: string
The width of a column can be set using the following unit options:
fr - fractional unit: Sets column widths as relative parts of the available row width, where “1fr” equals 1 part.
% - percentage unit: Sets the column width as a percentage of the available width. An error will be thrown if the sum of all column percentages exceeds 100%.
pt - point unit: Sets the column width as points on the page. An error will be thrown if the total points exceeds the available page width (See “Document size and measurements”).
Combining units: Units can also be combined, as long as the total combined width does not exceed the available row width.
Defined in
Document
Ƭ Document: SimpleDocument | DocumentWithSections
A document is the main data object that gets passed to renderPdf.
Document size and measurements:
The document is standard letter size (8.5in x 11in) and measured in PostScript points (612 x 792), where there are 72 points per inch. Some default values for the document include the following:
- tableGap: 18
- lineGap: 4.5
- page margin: 18
The available page widths for tables are as follows:
- landscape layout: 756 (792 - 2 * page margin)
- portrait layout: 576 (612 - 2 * page margin)
Defined in
DocumentOptions
Ƭ DocumentOptions: Object
Type declaration
| Name | Type | Description |
|---|---|---|
defaultFontSettings? | FontSetting | Default font setting through out document |
footers? | HeaderFooters | Document footers are displayed at the bottom of every page. |
headers? | HeaderFooters | Headers are displayed at the top of a pdf page. By default, the headers are only displayed on the first page. |
layout? | Layout | The orientation of the pdf document. Default is “landscape”. |
pageBreakRows? | PageBreakRows | Adds custom rows for page breaks |
pageNumbers? | boolean | Displays the document page number at the bottom of every page. Example: “Page 1 of 10” |
repeatReportHeaders? | boolean | Display the document headers on every page. |
repeatSectionHeaders? | boolean | Repeat section headers if a section is split between multiple pages. |
sectionPageNumbers? | boolean | Displays the section page number at the bottom of every page, and resets to 1 for every section. An error will be thrown if both pageNumbers and sectionPageNumbers are set to true. |
tableGap? | number | Sets the spacing between tables in the document. Default value is 18 (see “Document size and measurements”). Any section tableGap settings will override the document tableGap. |
timestamp? | boolean | Displays the timestamp at time of render on every page. Example: “Wed Apr 05 2023 04:05:58” |
watermark? | Watermark | Displays a Watermark on every page of the pdf. If a section has a watermark set, it will override the document watermark setting. |
Defined in
DocumentWithSections
Ƭ DocumentWithSections: DocumentOptions & { sections: Section[] }
Defined in
FontSetting
Ƭ FontSetting: Object
Style text font
Type declaration
| Name | Type | Description |
|---|---|---|
bold? | boolean | - |
boldFace? | string | Sets the font face for bold (when “bold” is true on the cell, row, or table). Default value is “Helvetica-Bold” See https://pdfkit.org/docs/text.html#fonts. |
color? | string | Example: “yellow” or ”#f6f6f6”. Default value is black. See https://pdfkit.org/docs/text.html#fonts |
fontFace? | string | Default is “Helvetica”. See https://pdfkit.org/docs/text.html#fonts |
fontSize? | number | Default value is 7. |
underline? | boolean | - |
Defined in
HeaderFooters
Ƭ HeaderFooters: Object
Type declaration
| Name | Type |
|---|---|
columns? | ColumnSetting[] |
rows | Row[] |
style? | RowOptions |
Defined in
HorizontalAlignment
Ƭ HorizontalAlignment: "left" | "center" | "right"
Defined in
Image
Ƭ Image: Object
A data object for adding an image to a row or cell. Accepts either a Buffer or string path.
Type declaration
| Name | Type | Description |
|---|---|---|
height | number | An image requires a height value (see “Document size and measurements”). |
image | Buffer | string | Sets the image from a buffer or path string. |
width? | number | - |
Defined in
ImageCell
Ƭ ImageCell: CellStyle & CellOptions & { image: Image }
An Image can be added to a row cell with optional styles.
Defined in
Layout
Ƭ Layout: "landscape" | "portrait"
Defined in
PageBreakRows
Ƭ PageBreakRows: Object
Adds rows at the bottom of each page where a table is split across multiple pages.
Type declaration
| Name | Type |
|---|---|
columns? | ColumnSetting[] |
rows | Row[] |
style? | RowOptions |
Defined in
Row
Ƭ Row: Object
A row contains data for an entry in a table, and can accept options to apply a default style to each cell in the row.
Type declaration
| Name | Type | Description |
|---|---|---|
data | (Cell | CellValue | TextTemplate)[] | A row’s data requires an array of either ImageCell or TextCell objects, strings, or numbers. |
image? | Image | Adds an image for the entire row with no other data. |
options? | RowOptions | Sets styling options for the cell. Overrides any row or table level styling options. |
Defined in
RowOptions
Ƭ RowOptions: CellStyle & FontSetting & { border?: boolean }
Set default cell styling for an entire row. Any options set at the cell level will override row options.
Defined in
Section
Ƭ Section: Object
A section consists of tables and optional headers. Sections can span multiple pages, and each new section begins on a new page.
Type declaration
| Name | Type | Description |
|---|---|---|
headers? | HeaderFooters | Section headers appear at the top of the page, below any document headers. If repeatSectionHeaders is set to true on the document, the section headers will be repeated if any sections span multiple pages. |
tableGap? | number | Sets the spacing between tables in the section. If not set, the section will inherit the document’s tableGap or the default value, 18 (see “Document size and measurements”). |
tables | Table[] | A section requires an array of tables. |
watermark? | Watermark | Accepts a Watermark data object for setting a diagonal text watermark on any of the section’s pages. Overrides any watermark setting on the document. |
Defined in
SimpleDocument
Ƭ SimpleDocument: DocumentOptions & { tables: Table[] }
Defined in
SnapshotResult
Ƭ SnapshotResult: Object
Type declaration
| Name | Type |
|---|---|
rendered | string |
snapshot | string |
Defined in
Table
Ƭ Table: Object
Tables consist of rows and optional headers. Column and style settings can be set at the table level.
Type declaration
| Name | Type | Description |
|---|---|---|
columns? | ColumnSetting[] | Sets the default column settings for each row in the table. |
headers? | Row[] | Sets table header rows, which will be repeated if a table spans multiple pages. |
rows | Row[] | Tables require an array of rows. |
style? | RowOptions | Sets the default style options for each row in the table. |
Defined in
TextCell
Ƭ TextCell: CellStyle & FontSetting & CellOptions & { value: CellValue }
A text cell includes data as a string or number, as well as optional styles.
Defined in
TextTemplate
Ƭ TextTemplate: Object
Type declaration
| Name | Type |
|---|---|
renderTemplate | RenderTemplateFn |
Defined in
TextTemplateCell
Ƭ TextTemplateCell: CellStyle & FontSetting & CellOptions & { template: TextTemplate }
Defined in
Unit
Ƭ Unit: "fr" | "%" | "pt"
Defined in
VerticalAlignment
Ƭ VerticalAlignment: "top" | "center" | "bottom"
Defined in
Watermark
Ƭ Watermark: Object
A data object for displaying a diagonal text watermark on a page.
Type declaration
| Name | Type | Description |
|---|---|---|
color? | string | Watermark text color (example: “yellow”, “#f6f6f6”). Default is “ff0000”. |
fontFace? | string | Font face of the watermark text. Default is “Helvetica-Bold”. See https://pdfkit.org/docs/text.html#fonts |
text | string | The watermark text |
Defined in
Functions
renderPdf
▸ renderPdf(document, response): Promise<NodeJS.WritableStream>
Writes a Document to a NodeJS.WriteableStream and returns the stream.
Parameters
| Name | Type |
|---|---|
document | Document |
response | WritableStream |
Returns
Promise<NodeJS.WritableStream>
Defined in
renderSnapshot
▸ renderSnapshot(path, document): Promise<SnapshotResult>
Creates and returns a new JSON snapshot of a given document rendering or returns the existing snapshot at a designated path, as well as returning the current rendering of the document. This is useful for seeing how new changes to a document compare to a previous state. NOTE: Image data is converted to MD5 hashes in order to limit the size of data in the snapshot document calls while still tracking changes.
Parameters
| Name | Type |
|---|---|
path | string |
document | Document |
Returns
Promise<SnapshotResult>
Defined in
rs
▸ rs(templates, ...args): TextTemplate
Parameters
| Name | Type |
|---|---|
templates | TemplateStringsArray |
...args | any[] |
Returns
Defined in
splitColumn
▸ splitColumn(value, measure, availableSpace): [string, string]
Use this function for the ‘splitFn’ ColumnSetting prop for a column that may have a variable height for its text, such as long notes text.
If a row is taller than the available vertical space on a page, this function splits the column text at a line break or space. Also, ‘(continued on next page)’ is inserted before the page break, and ‘(continued from previous page)’ is inserted after the page break.
Example:
1
2
3
4
5
6
7
import { splitColumn } from "report-script";
const columnSettings = [
{ width: "1fr" },
{ width: "2fr", splitFn: splitColumn, align: "left" },
{ width: "1fr" },
]
Parameters
| Name | Type |
|---|---|
value | string |
measure | (text: string) => VerticalMeasure |
availableSpace | number |
Returns
[string, string]