TableJS versions 1.0.0 - 1.4.* are for Angular 11 and lower. Versions 2.0.0+ are for Angular 12+.

DragAndDropGhostComponent

Selector: [tablejs-drag-and-drop-ghost]

import { DragAndDropGhostComponent } from '@tablejs/community';

Description:

A component that follows the cursor when dragging and dropping a column to alert the user of which column is being dragged.

Properties:

Name Description
@ViewChild (ref, {read: ViewContainerRef}) ref : any The ViewContainerRef used to bootstrap a custom ghost component.
left : number The component’s left position.
top : number The component’s top position.

Methods:

Name Description
updateView (template: TemplateRef<any>, context: object | null): void Resets the template and context that is rendered.

Components

GridComponent

Version Available: All Versions

Selector: [tablejs-grid]

import { GridComponent } from '@tablejs/community';

Description:

Wraps the table elements and acts as a container for all GridDirective functionality.

Properties:

Name Description
@Input() dragAndDropGhostFilter :
() => boolean
[Deprecated] Takes a function that returns a boolean value. This function filters elements out of the drag and drop ghost filter
@Input() linkClass :
string
A class that links various tablejs-grid components together to share the same behavior during column reordering and resizing
@Input() resizeColumnWidthByPercent :
boolean
Enables/disables column width resizing calculation by percentage. Column resize calculation defaults to using pixels.
@Output() columnResizeStart :
(e: ColumnResizeEvent) => void
Emits a single ColumnResizeEvent when a column begins resizing.
@Output() columnResize :
(e: ColumnResizeEvent) => void
Emits a ColumnResizeEvent every time the mouse moves during column resize.
@Output() columnResizeEnd :
(e: ColumnResizeEvent) => void
Emits a single ColumnResizeEvent when a column is released after it is resized.
@Output() columnReorderStart :
(e: ColumnReorderEvent) => void
Emits a single ColumnReorderEvent when a column begins reordering.
@Output() columnReorder :
(e: ColumnReorderEvent) => void
Emits a ColumnReorderEvent every time the mouse moves during column reorder.
@Output() columnReorderEnd :
(e: ColumnReorderEvent) => void
Emits a single ColumnReorderEvent when a column is released after it is reordered.
@Output() gridInitialize :
(e: ColumnReorderEvent) => void
Emits a single ColumnReorderEvent when a grid is initialized.
gridDirective : GridDirective [read-only] The GridDirective that is attached to this GridComponent.

ScrollPrevSpacerComponent

Selector: [tablejs-scroll-prev-spacer]

import { ScrollPrevSpacerComponent } from '@tablejs/community';

Description:

Alters DOM element spacing when new items are rendered when scrolling.

Properties:

Name Description
@ViewChild (template, {static: true}) template: any The template associated with the ScrollPrevSpacerComponent contents.

DataColClassesDirective

Version Available: All Versions

Selector: [tablejsDataColClasses]

import { DataColClassesDirective } from '@tablejs/community';

Description:

Groups multiple user-defined classes to a single column. This enables users to have sub columns or nested columns in the grid. Class names supplied to tablejsDataColClasses are to be separated by commas.

Properties:

Name Description
@Input() tablejsDataColClasses :
string
A comma delimited string of classes that will be affected during resize and reorder functionality.


Methods:

Method Description
cacheClassesOnElement (): void Saves the supplied classes in the header element’s dataClasses property.
registerColumnsWithDataClassesOnGridDirective (): void Ties the supplied classes with the header and registers them with the data grid.


Usage:

The tablejsDataColClasses in the example below tie th tags with corresponding td div elements. This allows TableJS to reorder, resize, show, and hide column headings and body information together.

<tablejs-grid>
    <table>
        <thead>
            <tr tablejsGridRow>
                <th tablejsDataColClasses="name">
                    <div> ... </div>
                </th>
                <th tablejsDataColClasses="price">
                    <div> ... </div>
                </th>
                <th tablejsDataColClasses="id">
                    <div> ... </div>
                </th>
            </tr>
        </thead>
        <tbody>
            <tr tablejsGridRow>
                <td>
                    <div tablejsDataColClass="name" initialWidth="150px"> 
                        {{ wishList.itemName }} 
                    </div>
                </td>
                <td>
                    <div tablejsDataColClass="price" initialWidth="150px"> 
                        {{ wishList.itemPrice }}
                    </div>
                </td>
                <td>
                    <div tablejsDataColClass="id" initialWidth="150px"> 
                        {{ wishList.itemID }} 
                    </div>
                </td>
            </tr>
        </tbody>
    </table>
</tablejs-grid>

DataColClassDirective

Version Available: All Versions

Selector: [tablejsDataColClass]

import { DataColClassDirective } from '@tablejs/community';

Description:

Ties a user-defined class to a tablejs-grid column. The class can be used to set initial CSS properties to a column. This directive should be placed on a div within a td or th element.

Properties:

Name Description
@Input() tablejsDataColClass :
string
The class name to be tied to the grid. Automatically puts a class on the element matching the string supplied.
@Input() initialWidth :
number
Sets the initial width of a column. Widths can be given either in pixels (px) or in percentage (%). Setting the initialWidth is not required, but greatly improves grid initialization performance.


Methods:

Method Description
registerInitialColumnWidthOnGridDirective (): void Registers an initial width value for the column with this directive.


Usage:

Below is an HTML implementation where an item is added to the wish list column, and the class “item-name” will be added to the td element’s div to provide a mechanism for styling this column.

<tablejs-grid>
    <table>
        <tbody>
            <tr tablejsGridRow>
                <td>
                    <div tablejsDataColClass="item-name"> 
                        {{ wishList.itemName }}
                    </div>
                </td>
            </tr>
        </tbody>
    </table>
</tablejs-grid>

When adding the property initialWidth to a tag with a speciying value, the initial column width is set. Which greatly improves grid initialization performance. Below is an HTML implementation for adding the property to a tag.

<td>
    <div tablejsDataColClass="item-name" initialWidth="50px"> 
        {{ wishList.itemName }}
    </div>
</td>

EditableCellDirective

Version Available: All Versions

Selector: [tablejsEditableCell]

import { EditableCellDirective } from '@tablejs/community';

Description:

Makes a cell editable in the grid. A custom validator function can be supplied for validating the value within the cell. The validator function is triggered on the input event of the input element. Regular expressions can also be added as part of the validation.

Properties:

Name Description
@Input() initialData:
any
Used to provide initial data into the cell.
@Input() validatorParams:
any[]
Additional parameters besides the input string supplied to the validator function.
@Input() regExp:
string
Regular expression used to validate the cell.
@Input() regExpFlags:
string
Regular expression flags.
@Input() list:
string[]
An array of valid values allowed in the editable cell.
containerDiv : HTMLDivElement Holds a created div element.
input : HTMLInputElement Holds a created input node.
dataList : HTMLDataListElement Holds inputted data list.
option : HTMLOptionElement Placeholder value for populating an empty data list.
lastText : string Placeholder value for most recent input element’s text value.
originalText : string Holds cell input element’s original text value.
lastValidInput : string Holds cell input element’s last valid text value.


Methods:

Method Description
@HostListener (document:keydown.enter, [$event]) onKeyDownHandler (event: KeyboardEvent): void Function that listens for keyboard event and modfies cell view based on corresponding event input.
@HostListener (click, [$event]) onClick (event: MouseEvent): void Function that listens for click event that focuses view on selected element.
@Input() validator
(inputStr: string, ..args: any[]) => boolean
User-defined function to validate the value of the cell.
@Output() cellInput ():
EventEmitter<any>
A user-defined function triggered with the edited value of an edited /changed cell.
@Output() cellFocusOut ():
EventEmitter<any>
Triggered when the focus of the cell has changed.
@Output() cellValidation ():
EventEmitter<any>
A user-defined function supplied to catch when a cell validates.
onFocusOut (): void Function that is fired when the cell loses focus.
createDataList (): void Function that creates a data list.
getCellObject (): any Function that will return a specfied cell object.
validateInput (): void Function that will validate cell input values.


Usage:

Below is an HTML implementation of turning a cell into an editable cell by using the tablejsEditableCell directive. A custom validator function is supplied to validate the cell’s contents.

Regular Expressions:

A regular expression can also be added as part of the validation. In the example below, we are adding a regular expression of ^[A-Za-z ]*$, which restricts the editable cell to only allow inputs of letters and spaces. Regular expression flags can also be added for more customizability. In this case, the g flag matches the regExp pattern multiple times, while the i flag makes the regExp case insensitive.

Event Emitters:

The (cellInput) event emitter calls a user-defined function when the user changes the cell’s value.

The (cellValidation) event emitter triggers a user-defined function when the cell validates.

The (cellFocusOut) event emitter is triggered when the focus of a cell has exited.

<td>
    <div tablejsDataColClass="name" initialWidth="22%">
        <span
            #nameSpanRef
            tablejsEditableCell
            [validator]="isNotEmpty"
            regExp="^[A-Za-z ]*$"
            regExpFlags="gi"
            (cellInput)="updateCellValue(purchase, 'name', $event)"
            (cellValidation)="onEditableCellValidated($event)"
            (cellFocusOut)="onEditableCellFocusOut($event)"
            >
            
        </span>
    </div>
</td>


Below is a Typescript implementation of the user-defined functions that the tablejsEditableCell event emitters call in the HTML example above. The updateCellValue function is called when the cellInput event emitter emits, and updates an item’s value with the new content provided. The onEditableCellValidated takes a boolean value which represents whether the cell input is valid. The onEditableCellFocusOut event emitter is setting the current span that most recently lost focus.

export class EditableCellsComponent {
    currentSpan: HTMLElement | null;
    currentCellIsValid: boolean = true;

    updateCellValue(item: any, varName: string, content: any) {
        if (content.currentValue !== content.lastValidInput) {
            item[varName] = content.originalValue;
        } else {
            item[varName] = content.currentValue;
        }
    }

    onEditableCellValidated(isValid: boolean) {
        this.currentCellIsValid = isValid;
    }

    onEditableCellFocusOut(e: Event) {
        this.currentSpan = e.target;
    }
}

Directives

GridDirective

Version Available: All Versions

Selector: [tablejsGrid]

import { GridDirective } from '@tablejs/community';

Description:

Wraps the table elements and is responsible for registering all the other grid-related directives and implementing their functionalities. The GridDirective acts as the control center for the TablejsGrid.

Properties:

Name Description
@Input() dragAndDropGhostFilter :
() => boolean
[Deprecated] Takes a function that returns a boolean value. This function filters elements out of the drag and drop ghost filter
@Input() linkClass :
string
A class that links various tablejs-grid components together to share the same behavior during column reordering and resizing
@Input() resizeColumnWidthByPercent :
boolean
Enables/disables column width resizing calculation by percentage. Column resize calculation defaults to using pixels.
@Output() columnResizeStart :
(e: ColumnResizeEvent) => void
Emits a single ColumnResizeEvent when a column begins resizing.
@Output() columnResize :
(e: ColumnResizeEvent) => void
Emits a ColumnResizeEvent every time the mouse moves during column resize.
@Output() columnResizeEnd :
(e: ColumnResizeEvent) => void
Emits a single ColumnResizeEvent when a column is released after it is resized.
@Output() columnReorderStart :
(e: ColumnReorderEvent) => void
Emits a single ColumnReorderEvent when a column begins reordering.
@Output() columnReorder :
(e: ColumnReorderEvent) => void
Emits a ColumnReorderEvent every time the mouse moves during column reorder.
@Output() columnReorderEnd :
(e: ColumnReorderEvent) => void
Emits a single ColumnReorderEvent when a column is released after it is reordered.
@Output() gridInitialize :
(e: GridEvent) => void
Emits a single GridEvent when the grid has initialized.
dragging : boolean Returns whether a column is being dragged.
reordering : boolean Returns whether a column is being reordered.
startX : number Holds horizontal coordinate of the users mouse pointer when a mouse event is triggered.
startY : number Holds vertical coordinate of the users mouse pointer when a mouse event is triggered.
viewport : HTMLElement The tbody tag to which the tablejsViewport directive belongs.
viewportID : string The id attribute value on the viewport element.
startingWidths : number[] Holds starting width of column in pixels.
minWidths : number[] Holds starting minimum width of column in pixels.
gridTemplateClasses : string[] Holds the list of CSS class names associated with the grid’s columns.
gridOrder : number[] Holds a numerical representation of column order in the grid.
classWidths : any[] Holds the widths of each column. If the columns are resized in pixels, these widths will be held as a number (e.g. 100). If the columns are resized in percentages, these will be held as string value percentages (e.g. “25%”).
draggingColumn : HTMLElement The th element currently being dragged.
colRangeGroups : number[][][] Holds the columns span ranges for each column group.
lastDraggedOverElement : any The last th column used for dragging.
resizableColumns : HTMLElement[] Holds a collection of all resizable columns.
resizableGrips : HTMLElement[] Hold a collection of elements that can be grabbed to resize columns.
reorderGrips : HTMLElement[] Hold a collection of elements that can be grabbed to reorder columns.
reorderableColumns : HTMLElement[] Holds a collection of columns that can be reordered.
columnsWithDataClasses : HTMLElement[] Holds a collection of th elements using a DataColCassesDirective.
rows : HTMLElement[] The tr elements on the grid containing a GridRowDirective.
infiniteScrollViewports : HTMLElement[] A list of tbody elements for scrolling table content.
initialWidths : any[] Returns in the initial width values of columns on the grid. Columns resized in pixels will return a number value (e.g. 100), while columns resized in percentages will return a percentage value as a string (e.g. “25%”).
parentGroups : Element[][] A collection of th elements, sorted by their order in the hierarchical tree.
elementsWithHighlight : any[] Hold a list of objects with elements and their corresponding highlight directions
dragAndDropGhostComponent : DragAndDropGhostComponent The DragAndDropGhostComponent displayed when the use is dragging a column.
dragOffsetX : number The horizontal offset of an element as it is being moved from its previous position.
dragOffsetY : number The vertical offset of an element as it is being moved from its previous position.
scrollViewportDirective : ScrollViewportDirective | null The ScrollViewportDirective associated with this GridDirective.
hiddenColumnChanges : Subject<IColumnHideChange> Observable for catching IColumnHideChange events.


Methods:

Method Description
canHideColumn (column: Element): boolean Returns true if a specified column can be hidden, else it returns false.
getFlattenedHierarchy (): IColumnHierarchy[] Returns the full hierarchy of columns and sub-columns in a flattened state.
getColumnHierarchy (): any Returns the full hierarchy of columns and sub-columns in a tree-like structure.
getHierarchySubColumns (item: IColumnData, levelCount: number): IColumnHierarchy[] Returns a list of IColumnHierarchy objects that pertain to an item’s sub-columns.
moveStyleContentToProminent (): void Moves the CSS for this grid later in the head tag so that it takes higher precedence
getRelatedHeader (element: Element): Element | any Returns the th element associated with the supplied th element. This is for grids using the sharing linkClass directive.
removeHighlights (elToExclude: HTMLElement | null, moveDirection: number = -2): void Removes all reorder column highlight classes on the grid.
removeElementHighlight (el: HTMLElement): void Removes the reorder column highlight classes for a single element on the grid.


GridRowDirective

Version Available: All Versions

Selector: [tablejsGridRow]

import { GridRowDirective } from '@tablejs/community';

Description:

Attaches a row element (tr) for use within the tablejs-grid.

Methods:

Method Description
registerRowsOnGridDirective (): void Function that adds a new row element to tablejs-grid.


Usage:

By attaching a table row element (tr), TableJS is able to track row information. Below is an HTML implementation for registering the Wish List Items row with TableJS.

<tablejs-grid>
    <table>
        <thead>
            <tr tablejsGridRow>
                <th>
                    <div>Wish List Items</div>
                <th>
            </tr>
        </thead>
    </table>
</tablejs-grid>

HideColumnIf

Version Available: 1.4.0 or higher, 2.1.0 or higher

Selector: [tablejsHideColumnIf], [tablejshidecolumnif], [tablejs-hide-column-if]

import { HideColumnIfDirective } from '@tablejs/community';

Description:

Provides a mechanism for hiding or showing columns.

Properties:

Name Description
@Input() tablejsHideColumnIf : boolean Setting this property to true will hide this column. Setting this property to false will show the column. Changing the status of this column’s visiblity may trigger a series of IColumnHideChange events. Nested columns will trigger as shown or hidden based on this column’s visibility. Parent columns in the IColumnHierarchy tree may be shown or hidden based on the change in this column’s visibility. If a parent’s children are all hidden by this column change, then the parent will change to hidden. If a parent needs to be visible because this column was made visible, then the parent will be shown as well.
HIDDEN_COLUMN_CLASS : string The CSS class added to the th element when the column is hidden.
changeTriggeredBy : IColumnHierarchy | null Holds the changed columm hierachy.
canHide : boolean Determines whether a specified column can be hidden. At least one column must be visible per table. Additionally, at least one nested column must be visible for its parent column to be visible.


Methods:

Name Description
getVisibleSiblingsByColumn (hierarchyList: IColumnHierarchy[], level: number): IColumnHierarchy[] Returns an array of IColumnHierarchy sibling objects that share a nesting level.
updateHeadersThatCanHide (): void Updates the visibility of columns that branch from the same IColumnHierarchy tree.
getLowestLevelColumnHierarchiesVisible (flattenedColumnHierarchy: IColumnHierarchy[]): IColumnHierarchy[] Returns a list of visible IColumnHierarchy elements. These elements will be at the lowest level in the hierarchical tree.
allColumnsShareTheSameAncestor (commonAncestor: IColumnHierarchy, columnHierarchies: IColumnHierarchy[], flattenedColumnHierarchy: IColumnHierarchy[]): boolean Returns whether the supplied ColumnHierarchy objects all have elements that share the same ancestor (e.g. parent, grandparent, etc.) in the hierarchical tree.
hideAllOffspring (columnHierarchy: IColumnHierarchy): void Hides all th elements that branch from this th. This includes children, grandchildren, great-grandchildren, etc.
showAllOffspring (columnHierarchy: IColumnHierarchy): void Shows all th elements that branch from this th. This includes children, grandchildren, great-grandchildren, etc.
allSiblingsAreHidden (columnHierarchy: IColumnHierarchy, flattenedColumnHierarchy: IColumnHierarchy[]): boolean Returns whether all of a th element’s siblings in a nested structure are hidden.
setAllAncestors (currentColumnHierarchy: IColumnHierarchy, flattenedColumnHierarchy: IColumnHierarchy[], hidden: boolean): void Sets the visibility of all of a column’s offspring (e.g. children, grandchildren, etc.).


Usage:

The HTML implementation below hides the column by setting the value of the tablejsHideColumnIf directive to true. Setting the directive to false would show the column.

<th
    tablejsDataColClasses="name"
    reorderCol
    [tablejsHideColumnIf]="true"
> </th>

InfiniteScrollDirective

Version Available: All Versions

Selector: [tablejsInfiniteScroll]

import { InfiniteScrollDirective } from '@tablejs/community'

Description:

[Deprecated] Used for proper resizing of the infinite scrolling component. Include this directive on your cdk-virtual-scroll-viewport component. It is recommended you use tablejsVirtualFor directive instead of cdkVirtualFor.

Methods:

Method Description
registerColumnOnGridDirective (): void Function that adds infinite scroll point to registered Column entries on Grid.


ReorderColDirective

Version Available: All Versions

Selector: [reorderCol]

import { ReorderColDirective } from '@tablejs/community';

Description:

Adding the reorderCol directive to a th or td element will enable drag and drop functionality on a specific column

Properties:

Name Description
@Input() reorderGhost:
TemplateRef<any>
The template to be rendered under the cursor when dragging a column.
@Input() reorderGhostContext:
Object|null = null
The data to be supplied to the template that is rendered under the cursor when dragging a column.


Methods:

Name Description
registerColumnOnGridDirective (): void Registers this column as reorderable in the GridDirective.


Usage:

Shown in the HTML below is an implementation of adding reorder drag and drop functionality by adding the reorderCol directive.

<tablejs-grid>
    <table>
        <thead>
            <tr tablejsGridRow>
                <th reorderCol>
                    <div> ... </div>
                </th>
                <th reorderCol>
                    <div> ... </div>
                </th>
                <th reorderCol>
                    <div> ... </div>
                </th>
            </tr>
        </thead>
    </table>
</tablejs-grid>

ReorderGripDirective

Version Available: All Versions

Selector: [reorderGrip]

import { ReorderGripDirective } from '@tablejs/community';

Description:

The reorderGrip directive is applied to an element which will be used as a handle for starting drag and drop functionality on a column.

Methods:

Name Description
registerGripOnGridDirective (): void Registers the element containing the reorderGrip directive with the GridDirective, and designates it as a handle for reordering.


Usage:

Adding reorderGrip to an element as shown in the HTML example below will designate that element as a handle for reordering a column.

<tablejs-grid>
    <table>
        <thead>
            <tr tablejsGridRow>
                <th tablejsDataColClasses="name" reorderCol>
                    <div>
                        <i class="fas fa-bars" reorderGrip> Name </i> 
                    </div>
                </th>
            </tr>
        </thead>
    </table>
</tablejs-grid>

ResizableGripDirective

Version Available: All Versions

Selector: [resizableGrip]

import { ResizableGripDirective } from '@tablejs/community';

Description:

The resizableGrip directive is added to an element to enable user-driven resize functionality on a column.

Methods:

Name Description
registerGripOnGridDirective (): void Registers the element containing the resizableGrip directive with the GridDirective, and designates it as a handle for resizing.


Usage:

In the HTML implementation below, a resizableGrip directive is added to the div element to provide a handle for resize functionality

<tablejs-grid>
    <table>
        <thead>
            <tr tablejsGridRow>
                <th tablejsDataColClasses="name">
                    <div class="vertical-resize-grip-line" resizableGrip> ... </div> 
                </th>
            </tr>
        </thead>
    </table>
</tablejs-grid>

ScrollViewportDirective

Version Available: 1.2.0 or higher, 2.0.0 or higher

Selector: [tablejsScrollViewport]

import { ScrollViewportDirective } from '@tablejs/community';

Description:

Attaches a viewport to the table to render virtual scrolling content.

Properties:

Name Description
@ContentChild(templateRef, { static: true }) templateRef : TemplateRef<any> Used to get the first template from TemplateRef directive.
@Input() templateID : string Holds id value of specific template.
@Input() generateCloneMethod :
((template: HTMLElement, items: any[], index: number) => Node)
Defines a function type that returns a node based on a specified template and its corresponding elements and index.
@Input() arrowUpSpeed : number Determines how many table rows are scrolled when pressing the up arrow
@Input() arrowDownSpeed : number Determines how many table rows are scrolled when pressing the down arrow
@Input() preItemOverflow : number The number of table rows to render before the first visible item in the viewport
@Input() postItemOverflow : number The number of table rows to render after the last visible item in the viewport
@Input() itemLoadLimit : number The maximum number of rows to render in the viewport. Defaults to Infinity. The viewport will automatically stop loading rows when they are no longer visible and have reached the postItemOverflow count.
@Input() fillViewportScrolling : any Forces the viewport to display all visible rows before rendering. This option reduces the white space seen from non-rendered rows when scrolling quickly.
@Output() itemAdded :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when a row is added to the viewport.
@Output() itemRemoved :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when a row is removed to the viewport.
@Output() itemUpdated :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when a row is rerendered.
@Output() rangeUpdated :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when the viewport range changes.
@Output() viewportScrolled :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when the viewport is scrolled.
@Output() viewportReady :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when the viewport is ready to intialize.
@Output() viewportInitialized :
(e: ScrollViewportEvent) => void
Emits a single ScrollViewportEvent when the viewport has intialized and is ready to scroll.
items : any[] | null The array of items that the viewport will use to render rows.
listElm : HTMLElement The table element that wraps the tbody viewport.
listContent : HTMLElement The tbody element that contains the scrollable content.
prevSpacer : HTMLElement The tr element that provides a space between the beginning of the row content and the first displayed row.
postSpacer : HTMLElement The tr element that provides a space between the last displayed row item and the end of the content.
gridDirective : GridDirective The related GridDirective.
virtualForChangesSubscription$ : Subscription Listens for changes made to the items array.
range : Range A Range object that contains the start and end indices of the displayed items within the viewport.
lastRange : Range A Range object that contains the start and end indices of the items that were displayed within the viewport before the last scroll event.
lastScrollTop : number The value in pixels that the viewport was last scrolled down.
currentScrollTop : number The value in pixels that the viewport is currently scrolled down.
currentScrollChange : number The variance in pixels between the current and previous scroll position.
scrollChangeByFirstIndexedItem : number The amount of pixels hidden by the viewport for the item at range.startIndex.
virtualNexus : IVirtualNexus Provides access to the related VirtualForDirective.
pauseViewportRenderUpdates : boolean Defaults to false. When true, this property prevents the viewport from updating items.


Methods:

Method Description
handleScroll (e: Event): void The function called every time the viewport is scrolled.
rerenderRowAt (index: number, updateScrollPosition: boolean = false): void Redraws the row at the supplied index. [Optional] Force the scroll position to update.
scrollToBottom (): void Scroll the viewport to the bottom.
scrollToTop (): void Scroll the viewport to the top.
pageUp (): void Scroll the viewport up one set of items.
pageDown (): void Scroll the viewport down one set of items.
updateItems (items: any[], scrollToOptions: any = {index: -1, scrollAfterIndexedItem: 0 }): void Update item list and reset scrolling.
resetToInitialValues (): void Resets all the viewport variables to their defaults.
recalculateRowHeight (index: number): void Reevaluates a row’s height.
getPreviousSibling (el: Node): any Retrieve a node renderered prior to the supplied node.
getNextSibling (el: Node): any Retrieve a node renderered after to the supplied node.
showRange (startIndex: number, endIndex: number, overflow: number = 0): void Force the viewport to display a designated range.
getDisplayedContentsHeight (): number Get the height in pixels of all the contents rendered in the viewport.
refreshContainerHeight (): void Updates the container height based on visible rows.
allItemsFitViewport (recalculateContainerHeight: boolean = false): boolean Returns whether all the rendered rows fit within the bounds of the viewport.
getCurrentScrollPosition (): any Returns an object with details about the current scroll position.
getCloneFromTemplateRef (index: number): HTMLElement Returns an HTMLElement generated by cloning the template at the supplied row index.
scrollToExact (index: number, overflow: number = 0): void Scroll the viewport to the item at the specified index. The overflow is the pixel amount that the viewport should scroll past the beginning of the first item.
refreshViewport (recalculateRows: boolean): void Forces the viewport to update.
updateScrollFromRange (newRange: Range): void Updates the scroll position based on the updated range supplied.


Usage:

Below is an HTML implementation of attaching a viewport to the table to render virtual scrolling content.

Property Binding:

Both arrowDownSpeed and arrowUpSpeed are defined to dictate how many rows are scrolled when each corresponding buttons are pressed, in this case it is 1 row. preItemOverflow and postItemOverflow defines how many rows are rendered before the first visible item in the viewport, in this case it is 2 rows.

Event Emitters:

(itemAdded) emits an event when a new row is added.

(itemRemoved) emits an event when a row is deleted.

(itemUpdated) emits an event when an existing row is rerendered.

(rangeUpdated) emits an event when the viewport range changes.

(viewportScrolled) emits an event when viewport is scrolled.

(viewportReady) emits an event when viewport is ready to be initialized.

(viewportInitialized) emits an event when the viewport has intialized and is ready to scroll.

<tablejs-grid>
    <table 
        tablejsScrollViewport
        arrowDownSpeed="1"
        arrowUpSpeed="1"
        preItemOverflow="2"
        postItemOverflow="2"
        (itemAdded)="itemAdded($event)"
        (itemRemoved)="itemRemoved($event)"
        (itemUpdated)="itemUpdated($event)"
        (rangeUpdated)="rangeUpdated($event)"
        (viewportScrolled)="viewportScrolled($event)"
        (viewportReady)="viewportReady($event)"
        (viewportInitialized)="viewportInitialized($event)"
    > </table>
</tablejs-grid>

Below is a Typescript example implementation for all event emitter functions specified above.

itemAdded(e: ScrollViewportEvent): void {}
itemRemoved(e: ScrollViewportEvent): void {}
itemUpdated(e: ScrollViewportEvent): void {}
rangeUpdated(e: ScrollViewportEvent): void {}
viewportScrolled(e: ScrollViewportEvent): void {}
viewportReady(e: any): void {}
viewportInitialized(e: any): void {}

Keyboard Shortcuts for Windows:

Keys Description
End Scroll to End
Home Scroll to Top
Page Up Page Up
Page Down Page Down
Up Arrow Up 1 Row
Down Arrow Down 1 Row


Keyboard Shortcuts for Mac:

Keys Description
End Command + Up Arrow
Home Command + Down Arrow
Page Up Fn + Up Arrow
Page Down Fn + Down Arrow
Up Arrow Up 1 Row
Down Arrow Down 1 Row


TablejsViewport

Version Available: 1.2.0 or higher, 2.0.0 or higher

Selector: [tablejsViewport]

Description:

Designates which tbody tag to display viewport items. (e.g.: <tbody tablejsViewport>...</tbody>)

Usage:

Below is an HTML implementation of designating a tbody tag as the viewport for displaying table row items.

<tablejs-grid>
    <table>
        <thead>
            <tr>
                <th>
                    <div> ... </div>
                </th>
            <tr>
        </thead>
        <tbody tablejsViewport>
            <tr>
                <td>
                    <div> ... </div>
                </td>
            </tr>
        </tbody>
    </table>
</tablejs-grid>    

VirtualForDirective

Version Available: 1.2.0 or higher, 2.0.0 or higher

Selector: [tablejsVirtualFor]

import { VirtualForDirective } from '@tablejs/community';

Description:

*tablejsVirtualFor replaces *ngFor inside of a <table tablejsScrollViewport>, supporting the exact same API as *ngFor. The VirtualForDirective renders only tr items that are visible within the range of the tablejsScrollViewport. (Eg: <tr *tablejsVirtualFor="let item of items; let i = index; trackBy: trackItem">...</tr>)

Properties:

Name Description
@Input() tablejsVirtualForOf
(tablejsVirtualForOf: U|undefined|null): void
[write-only] The value of the iterable expression, which can be used as a template input variable.
@Input() tablejsVirtualForTemplate
(value: TemplateRef<TablejsForOfContext<T, U>>): void
[write-only] A reference to the template that is stamped out for each item in the iterable.
@Input() tablejsVirtualForTrackBy :
TrackByFunction<T> | undefined
[read-only] Specifies a custom TrackByFunction to compute the identity of items in an iterable.
virtualNexus : IVirtualNexus The nexus that ties a scrollViewportDirective with a virtualForDirective
changes : Subject<any> An Observable that dispatches changes made to the list of items.
rangeUpdatedSubscription$ : Subscription Listens for any changes made to the Range being displayed in a viewport.
template : TemplateRef<TablejsForOfContext<T, U>> [read-only] The template used for rendering rows in the viewport.


Methods:

Name Description
rangeIsDifferent (range1: Range, range2 Range): boolean Returns whether two ranges contain the same starting and ending values.
renderedItemsNeedUpdate (): boolean Determines if items need to be re-rendered.
updateItems (): void Updates items if it is determined that changes have been made to the list of items, or if it is determined they need to be re-rendered.


Usage:

Below is an HTML use case for applying the *tablejsVirtualFor directive. The filteredItems variable on the template is an array of items that we wish to display during scrolling. These items are dynamically added to and removed from the viewport as needed based on the scroll position.

<tablejs-grid>
    <table tablejsScrollViewport>
        <thead>
            <tr tablejsGridRow>
                <th tablejsDataColClasses="name">
                    <div> Name </div>
                </th>
                <th tablejsDataColClasses="id">
                    <div> ID </div>
                </th>
            <tr>
        </thead>
        <tbody tablejsViewport>
            <tr *tablejsVirtualFor="let item of filteredItems">
                <td>
                    <div tablejsDataColClass="name"> 
                        {{ item.name }}    
                    </div>
                </td>
                <td>
                    <div tablejsDataColClass="id"> 
                        {{ item.id }}
                    </div>
                </td>
            </tr>
        </tbody>
    </table>
</tablejs-grid>    

FilterSortService

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { FilterSortService } from '@tablejs/community';

Description:

FilterSortService provides several methods for filtering and sorting table data using SortOptions and FilterOptions objects.

Properties:

Property Description
currentFilterOptions:
IFilterOptions
Returns the IFilterOptions currently being used to filter an array of items
currentSortOptions:
ISortOptions
Returns the ISortOptions currently being used to sort an array of items
itemsBeingFilteredAndSorted:
any[]
The array of items being sorted or filtered
sortDirection:
number
Returns the direction the of the current ISortOptions being sorted (eg. SortDirection.ASCENDING,, SortDirection.DESCENDING, SortDirection.NONE)
ignoreCase:
boolean
Returns whether the current ISortOptions or IFilterOptions is ignoring case-sensitivity


Methods:

Method
filterAndSortItems
Returns an array of items filtered by the variableIdentifiers supplied to the corresponding IFilterOptions.
Parameters
items:
any[]
filterOptions:
IFilterOptions | IFilterOptions[] | FilterOptions | FilterOptions[]
sortOptions:
ISortOptions | ISortOptions[] | SortOptions | SortOptions[]
Returns
any[]


Method
getFilterValuesFromPropertyIndentifiers
Returns an array of values usable in a comparator function. These values are derived from FilterOptions.variableIdentifiers. If no variable identifier is supplied, this method will return an array containing only the the single item being filtered.
Parameters
value:
any
Returns
any[]


Method
getSortValuesFromPropertyIdentifiers
Returns an array of two values for comparison in a comparator function. These values are derived from SortOptions.variableIdentifier. If no variable identifier is supplied, this method will return an array containing the original valueA and valueB values for comparison.
Parameters
valueA:
any
valueB:
any
Returns
any[]


Method
isString
Determines whether a given value is a string.
Parameters
val:
any
Returns
boolean


Method
filterItemsByVarNames
Returns an array of filtered items by their name, using the items IFilterOptions.
Parameters
items:
any[]
filterOptions:
IFilterOptions | FilterOptions | null
Returns
any[]


Method
sortItemsByVarName
Returns an array of items sorted by the variableIdentifier supplied to the corresponding ISortOptions.
Parameters
items:
any[]
sortOptions:
ISortOptions | null
Returns
any[]


Method
multiSortItemsByVarName
Returns an array of items sorted by the variableIdentifiers from multiple ISortOptions.
Parameters
items:
any[]
sortOptionsGroup:
(ISortOptions | null)[] | (SortOptions | null)[]
Returns
any[]


Usage:

Below is a Typescript example that utilizes the FilterSortService.filterAndSortItems method to sort an array of objects that contain ID and name properties. The items are filtered and sorted based on a set of user-defined filter and sort options.

import {SortComparator, FilterComparator} from '@tablejs/community';

export class FilterSortServiceExample {
    
    employees: any[] = [
        {id: 2, name: 'jill'}, 
        {id: 4, name: 'bill'}, 
        {id: 8, name: 'mike'}, 
        {id: 1, name: 'bob'}, 
        {id: 21, name: 'kyle'}
    ];
    mySortOptions: SortOptions;
    myFilterOptions: FilterOptions;

    constructor(private filterSortService: FilterSortService){
        this.setSortOptions();
        this.setFilterOptions();
        this.filterEmployees();
    }

    setSortOptions(): void {
        this.mySortOptions = new SortOptions(
            'id',
            SortComparator.NUMERIC
            SortDirection.NONE
        );
    }

    setFilterOptions(): void {
        this.myFilterOptions = new FilterOptions(
            'name',
            FilterComparator.STARTS_WITH, 
            'b'
        );
    }

    filterEmployees(): void {
        sortOptions.nextSortDirection(); // Changes sortOptions's sort direction to SortDirection.ASCENDING

        let filteredEmployees: any[] = this.filterSortService.filterAndSortItems(
            this.employees,
            this.myFilterOptions,
            this.mySortOptions
        );
        console.log(filteredEmployees); // filteredEmployees = [{id: 1, name: 'bob'}, {id: 4, name: 'bill'}]
    }
}

ColumnReorderEvent

Versions Available: All Versions

import { ColumnReorderEvent } from '@tablejs/community';

Description:

Emits a ColumnReorderEvent every time the mouse moves during column reorder. The ColumnReorderEvent contains the following data:

Types:

Type
ON_REORDER : string = ‘onReorder’
[read-only] event that triggers when a column is being reordered.
Property Description
columnDragged : Element Contains the HTML element that triggered the reorder.
columnHovered : Element Contains the HTML element over which the currently dragged element is hovered during reorder.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnReorderEvent.ON_REORDER


Type
ON_REORDER_START : string = ‘onReorderStart’
[read-only] event that triggers when a column is starting to be reordered.
Property Description
columnDragged : Element Contains the HTML element that triggered the reorder.
columnHovered : Element Contains the HTML element over which the currently dragged element is hovered at the start of reorder.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnReorderEvent.ON_REORDER_START


Type
ON_REORDER_END : string = ‘onReorderEnd’
[read-only] event that triggers when a column is finished being reordered.
Property Description
columnDragged : Element Contains the HTML element that triggered the reorder.
columnHovered : Element Contains the HTML element over which the currently dragged element is hovered at the end of reorder.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnReorderEvent.ON_REORDER_END


Usage:

The HTML example below is assigning each of the three event emitters below and declaring the functions that will be called when each of these events is triggered. An event object is being passed to each of these functions.

Event Emitters:

(columnReorderStart) emits an event when a column is starting to be reordered.

(columnReorder) emits an event when a column is being reordered.

(columnReorderEnd) emits an event when a column is finished being reordered.

<tablejs-grid
    (columnReorderStart)="columnReorderStart($event)"
    (columnReorder)="columnReorder($event)"
    (columnReorderEnd)="columnReorderEnd($event)"
  > </tablejs-grid>

The Typescript below declares the functions that will catch each of the reorder events.

columnReorderStart(e: ColumnReorderEvent) {
    console.log('column reorder started: \n', e);
}
columnReorder(e: ColumnReorderEvent) {
    console.log('column reordering: \n', e);
}
columnReorderEnd(e: ColumnReorderEvent) {
    console.log('column reorder ended: \n', e);
}


Events

ColumnResizeEvent

Version Available: All Versions

import { ColumnResizeEvent } from '@tablejs/community';

Description:

Emits a ColumnResizeEvent every time the mouse moves during column resize. The ColumnResizeEvent contains the following data:

Types:

Type
ON_RESIZE : string = ‘onResize’
[read-only] event that triggers when a column is being resized.
Property Description
columnMinWidth : number Contains the minimum width value of the column during resize.
columnWidth : number Contains the current width of the column during resize.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnResizeEvent.ON_RESIZE
classesBeingResized : string[] An array that holds all classes currently being resized.


Type
ON_RESIZE_START : string = ‘onResizeStart’
[read-only] event that triggers when at the start of a column resize.
Property Description
columnMinWidth : number Contains the minimum width value of the column at the start of the resize.
columnWidth : number Contains the current width of the column at the start of the resize.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnResizeEvent.ON_RESIZE_START
classesBeingResized : string[] An array that holds all classes about to be resized.


Type
ON_RESIZE_END : string = ‘onResizeEnd’
[read-only] event that triggers when a column is finished being resized.
Property Description
columnMinWidth : number Contains the minimum width value of the column at the end of the resize.
columnWidth : number Contains the current width of the column at the end of the resize.
pointerEvent : any Holds details of the users actions in the browser through a PointerEvent.
type : string ColumnResizeEvent.ON_RESIZE_END
classesBeingResized : string[] An array that holds all classes that were just resized.


Usage:

The HTML example below is assigning each of the three event emitters below and declaring the functions that will be called when each of these events is triggered. An event object is being passed to each of these functions.

Event Emitters:

(columnResizeStart) emits an event at the start of the column resize.

(columnResize) emits an event when a column is being resized.

(columnResizeEnd) emits an event when a column is finished resizing.

<tablejs-grid 
    (columnResizeStart)="columnResizeStart($event)"
    (columnResize)="columnResize($event)"
    (columnResizeEnd)="columnResizeEnd($event)"
  > </tablejs-grid>

The Typescript below declares the functions that will catch each of the resize events.

columnResizeStart(e: ColumnResizeEvent) {
    console.log('column resize started: \n', e);
}
columnResize(e: ColumnResizeEvent) {
    console.log('column resizing: \n', e);
}
columnResizeEnd(e: ColumnResizeEvent) {
    console.log('column resize ended: \n', e);
}


GridEvent

Version Available: All Versions

import { GridEvent } from '@tablejs/community';

Description:

Emits a GridEvent when the table has been initialized. The GridEvent contains the following data:

Type
ON_INITIALIZED : string = ‘onInitialized’
[read-only] A GridEvent fired when the grid has initialized.
Properties Description
gridComponent : GridComponent Contains the component to which the table is attached. Must have a component attached for grid to be initialized.
gridElement : HTMLElement Contains the tablejs-grid element to which the table is attached. Must have tablejs-grid element attached for grid to be initialized.
type : string GridEvent.ON_INITIALIZED

ScrollViewportEvent

Version Available: 1.2.0 or higher, 2.0.0 or higher

import { ScrollViewportEvent } from '@tablejs/community';

Description:

Event type for when the ScrollViewportDirective triggers an event. The ScrollViewportEvent contains the following data:

Types:

Type
ON_ITEM_ADDED : string = ‘onItemAdded’
The ScrollViewportEvent triggered when a new element is added in the ScrollViewportDirective.
Properties Description
element : HTMLElement The element that was added to the viewport.
index : HTMLElement The index from the array of items supplied to the VirtualForDirective at which the item was added.
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The added element’s corresponding HTMLElement to which the ScrollViewportDirective is attached.
range : Range The range of indices from the item array that are currently rendered in the viewport.


Type
ON_ITEM_REMOVED : string = ‘onItemRemoved’
The ScrollViewportEvent triggered when an existing element is removed from the ScrollViewportDirective.
Properties Description
element : HTMLElement The element that was removed from the viewport.
index : HTMLElement The index from the array of items supplied to the VirtualForDirective at which the item was removed.
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The removed element’s corresponding HTMLElement to which the ScrollViewportDirective is attached.
range : Range The range of indices from the item array that are currently rendered in the viewport.


Type
ON_ITEM_UPDATED : string = ‘onItemUpdated’
The ScrollViewportEvent triggered when an exisiting element is updated from the ScrollViewportDirective.
Properties Description
element : HTMLElement The element that was updated in the viewport.
index : HTMLElement The index from the array of items supplied to the VirtualForDirective at which the item was updated.
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The updated element’s corresponding HTMLElement to which the ScrollViewportDirective is attached.
range : Range The range of indices from the item array that are currently rendered in the viewport.


Type
ON_RANGE_UPDATED : string = ‘onRangeUpdated’
The ScrollViewportEvent triggered when the current range of rendered elements is altered from the ScrollViewportDirective.
Properties Description
range : Range The range of indices from the item array that are currently rendered in the viewport.
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The HTMLElement to which the ScrollViewportDirective is attached.


Type
ON_VIEWPORT_SCROLLED : string = ‘onViewportScrolled’
The ScrollViewportEvent triggered when the viewport is scrolled
Properties Description
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The HTMLElement to which the ScrollViewportDirective is attached.
range : Range The range of indices from the item array that are currently rendered in the viewport.
scrollTop : number The offset between the beginning of the scroll viewport and the first rendered element.
firstItemOverflow : number The amount of pixels past the first visible item that the user has scrolled.


Type
ON_VIEWPORT_READY : string = ‘onViewportReady’
The ScrollViewportEvent triggered when the viewport has completed its first render.
Properties Description
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The HTMLElement to which the ScrollViewportDirective is attached.


Type
ON_VIEWPORT_INITIALIZED : string = ‘onViewportInitialized’
The ScrollViewportEvent triggered when the viewport is initialized from the ScrollViewportDirective.
Properties Description
viewport : ScrollViewportDirective The ScrollViewportDirective that triggered the event.
viewportElement : HTMLElement The HTMLElement to which the ScrollViewportDirective is attached.


Usage:

The example below demonstrates how one would designate functions to catch different kinds of ScrollViewportEvent objects.

Event Emitters:

(itemAdded) emits an event when a new item is added to the viewport (tbody) and calls the itemAdded function with the event ($event) emitted as a parameter.

(itemRemoved) emits an event when an existing element is removed from the viewport (tbody) and calls the itemRemoved function with the event ($event) emitted as a parameter.

(itemUpdated) emits an event when an existing element is updated within the viewport (tbody) and calls the itemUpdated function with the event ($event) emitted as a parameter.

(rangeUpdated) emits an event when the current range of rendered elements within the viewport (tbody) is altered. The rangeUpdated function is called with the event ($event) emitted as a parameter.

(viewportScrolled) emits an event when the viewport (tbody) is scrolled. The viewportScrolled function is called using the event ($event) emitted as a parameter.

(viewportReady) emits an event when the viewport (tbody) has completed its first render. The viewportReady function is called with the event ($event) emitted as a parameter.

(viewportInitialized) emits an event when the viewport (tbody) is initialized. The viewportInitialized function is called with the event ($event) emitted as a parameter.

<tablejs-grid>
    <table
        tablejsScrollViewport
        (itemAdded)="itemAdded($event)"
        (itemRemoved)="itemRemoved($event)"
        (itemUpdated)="itemUpdated($event)"
        (rangeUpdated)="rangeUpdated($event)"
        (viewportScrolled)="viewportScrolled($event)"
        (viewportReady)="viewportReady($event)"
        (viewportInitialized)="viewportInitialized($event)"
    > </table>
</tablejs-grid>

Below is a typescript implementation for the ScrollViewportEvents shown above.

itemAdded(e: ScrollViewportEvent): void {/*Run desired code when an item is added to the viewport*/}
itemRemoved(e: ScrollViewportEvent): void {/*Run desired code when an item is removed from the viewport*/}
itemUpdated(e: ScrollViewportEvent): void {/*Run desired code when an item is updated in the viewport*/}
rangeUpdated(e: ScrollViewportEvent): void {/*Run desired code when the range is updated in the viewport*/}
viewportScrolled(e: ScrollViewportEvent): void {/*Run desired code when the viewport is scrolled*/}
viewportReady(e: any): void {/*Run desired code when the viewport is ready*/}
viewportInitialized(e: any): void {/*Run desired code when the viewport is initialized*/}


Comparator

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { Comparator } from '@tablejs/community';

Description:

Base class for setting static comparator functions. See also the FilterComparator and SortComparator classes

Properties:

Property Description
filterSortService : FilterSortService The FilterSortService related to this Comparator.


Methods:

Method Description
getCurrentSortOptions():
ISortOptions | null
For use inside a comparator function. Retrieves the current ISortOptions being used during item sort
getCurrentFilterOptions():
IFilterOptions | null
For use inside a comparator function. Retrieves the current IFilterOptions being used during item filtration
isString(val: any):
boolean
Returns whether the val parameter supplied is a string


Usage:

See FilterComparator and SortComparator

FilterComparator

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { FilterComparator } from '@tablejs/community';

Description:

Extends the Comparator class. Contains static comparator functions for use in filtering arrays.

Methods:

Method
getModifiedValue
[static] Returns a value modified by a variableMappers function. If an array of variableMappers functions is supplied, an index value for the desired variableMappers function is required.
Parameters
value: any
variableMappers:
Function | (Function | null)[] | null
index: number
Returns
any


Method
CONTAINS_STRING
[static] A comparator function that filters items from an array by evaluating if the value from the array contains the string provided by the FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
CONTAINS_WORD
[static] A comparator function that filters items from an array by evaluating if the value from the array contains the word provided by the FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
STARTS_WITH
[static] A comparator function that filters items from an array by evaluating if the value from the array starts with the provided FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
ENDS_WITH
[static] A comparator function that filters items from an array by evaluating if the value from the array ends with the provided FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
WORD_STARTS_WITH
[static] A comparator function that filters items from an array by evaluating if the value from the array has a word that starts with the provided FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
WORD_ENDS_WITH
[static] A comparator function that filters items from an array by evaluating if the value from the array has a word that ends with the provided FilterOptions.filterValue
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
EQUALS
[static] A comparator function that filters items from an array by evaluating if the value from the array equals (==) the provided FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
STRICT_EQUALS
[static] A comparator function that filters items from an array by evaluating if the value from the array strictly equals (===) the provided FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
LESS_THAN
[static] A comparator function that filters items from an array by evaluating if the value from the array is less than FilterOptions.filterValue provided.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
GREATER_THAN
[static] A comparator function that filters items from an array by evaluating if the value from the array is greater than FilterOptions.filterValue provided.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
LESS_THAN_OR_EQUAL
[static] A comparator function that filters items from an array by evaluating if the value from the array is less than or equal to the FilterOptions.filterValue provided.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
GREATER_THAN_OR_EQUAL
[static] A comparator function that filters items from an array by evaluating if the value from the array is greater than or equal to the FilterOptions.filterValue provided.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_AFTER_DATE
[static] A comparator function that filters items from an array by evaluating if the Date value from the array comes after the date provided by the FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_BEFORE_DATE
[static] A comparator function that filters items from an array by evaluating if the Date value from the array comes before the date provided by the FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
DATE_IS
[static] A comparator function that filters items from an array by evaluating if the Date value from the array is the same as the date provided by the FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_ON_OR_AFTER_DATE
[static] A comparator function that filters items from an array by evaluating if the Date value from the array is on or after the date provided by the FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_ON_OR_BEFORE_DATE
[static] A comparator function that filters items from an array by evaluating if the Date value from the array is on or before the date provided by the FilterOptions.filterValue.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_TRUE
[static] A comparator function that filters items from an array by evaluating if the value from the array is true.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_FALSE
[static] A comparator function that filters items from an array by evaluating if the value from the array is false.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_TRUTHY
[static] A comparator function that filters items from an array by evaluating if the value from the array is truthy.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
IS_FALSY
[static] A comparator function that filters items from an array by evaluating if the value from the array is falsy.
Parameters
value: any
index?: number
array?: any[]
Returns
boolean


Method
triggerNoFilterOptionsError
[static] A function that throws an error whenever a FilterOptions is not specified.
Returns
void


Usage:

See FilterOptions

FilterOptions

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { FilterOptions } from '@tablejs/community';

Description:

A set of filter options for filtering an array of items. Implements IFilterOptions.

Properties:

Property Description
id: string An identifier for this set of options
variableIdentifiers:
string | string[]
A property or array of property identifiers used to determine the value from an item that should be filtered (ex: 'name' returns the value of item.name)
ignoreCase: boolean Option to ignore case-sensitivity
ignoreTimeOfDay: boolean Option to ignore the time of day when comparing Date objects
comparator:
(element: any, index: number, array: any[]) => boolean
A function used for comparing values. If the function returns true, the item will be pushed into the filtered array. A false return value will exclude the compared item from the filtered array
variableMappers?:
Function | Function[]
Optional Function(s) that will modify the value(s) of an item before it is filtered. Filtering comparison will occur on the modified value
filterValue:
Function | Function[]
The value by which all filtering should be compared
matchType:
string | MatchType.ALL | MatchType.ANY
A match type to determine whether a comparator function requires a single identifier to match the filterValue or all identifiers


Usage:

Below is an Typescript implementation where an array of objects holding IDs are all filtered by their ID value. In this case, IDs that are greater than or equal to 2 will be returned.

import {FilterOptions, FilterComparator, FilterSortService, MatchType} from '@tablejs/community';

export class VariableIdentifier implements OnInit {
    items: any[] = [{id: 1}, {id: 4}, {id: 2}, {id: 8}, {id: 21}];
    myFilterOptions: FilterOptions;

    constructor(private filterSortService: FilterSortService){
        this.getIDsGreaterThanOrEqualToTwo();
    }

    getIDsGreaterThanOrEqualToTwo(): void {
        this.myFilterOptions = new FilterOptions(
            'id',
            FilterComparator.GREATER_THAN_OR_EQUAL,
            2,
            MatchType.ALL,
            true
        );

        let filteredValues: any[] = this.filterSortService.filterAndSortItems(
            this.items,
            this.myFilterOptions,
            null
        );
        console.log(filteredValues); // filteredValues = [{id: 4}, {id: 2}, {id: 8}, {id: 21}]
    }
}


Using MatchType.ALL:

Below is a Typescript implementation where an array of objects holding a person’s favorite food are all filtered by a common string they each contain. In this case, the objects containing a given person’s name and their favorite food will both be filtered if both properties’ values contain the string ‘Che’.

import {FilterOptions, FilterComparator, FilterSortService, MatchType} from '@tablejs/community';

export class MultipleVariableIdentifier implements OnInit {
    characterDetails: any[] = [{name: 'Chester Cheetah', food: 'Cheetos'}, {name: 'Mickey Mouse', food: 'Cheese'}];
    myFilterOptions: FilterOptions;

    constructor(private filterSortService: FilterSortService){
        this.getFavoriteFood();
    }

    getFavoriteFood(): void {
        this.myFilterOptions = new FilterOptions(
            ['name', 'food'],
            FilterComparator.CONTAINS_STRING,
            'Che',
            MatchType.ALL,  // By using MatchType.ALL, each of the variable identifiers' values must match in order for 
                           // the item to be filtered.
            true
        );

        let filteredValues: any[] = this.filterSortService.filterAndSortItems(
            this.characterDetails,
            this.myFilterOptions,
            null
        );
        console.log(filteredValues); // filteredValues = [{name: 'Chester Cheetah', food: 'Cheetos'}]
    }
}


Using MatchType.ANY:

Below is a Typescript implementation where using MatchType.ANY will return an item if either its price or its tax rate are greater than 0.099.

import {FilterOptions, FilterComparator, FilterSortService, MatchType} from '@tablejs/community';

export class MatchTypeAny implements OnInit {
    items: any[] = [{price: 342.07, taxRate: 0.095}, {price: 12.19, taxRate: 0.1}, {price: 0.099, taxRate: 0.05}];
    myFilterOptions: FilterOptions;

    constructor(private filterSortService: FilterSortService){
        this.filterPriceAndTaxRates();
    }

    filterPriceAndTaxRates(): void {
        this.myFilterOptions = new FilterOptions(
            ['price', 'tax'],
            FilterComparator.GREATER_THAN,
            0.099,
            MatchType.ANY, 
            true
        );

        let filteredValues: any[] = this.filterSortService.filterAndSortItems(
            this.items,
            this.myFilterOptions,
            null
        );
        console.log(filteredValues); // filteredValues = [{price: 342.07, taxRate: 0.095}, {price: 12.19, taxRate: 0.1}]
    }
}


Filtering Using Mapped Variables:

Below is a Typescript implementation that uses a mapper function to convert the numeric price value into a string value. Filtering is then done on the string value returned from the mapper function.

import {FilterOptions, FilterComparator, FilterSortService, MatchType} from '@tablejs/community';

export class VariableMapperExample implements OnInit {
    items: any[] = [{price: 342.07}, {price: 12.19}, {price: 45.59}, {price: 21.00}];
    containsStringFilterOptions: FilterOptions;

    constructor(private filterSortService: FilterSortService){
        this.filterOnPriceAsString();
    }

    filterOnPriceAsString(): void {
        this.containsStringFilterOptions = new FilterOptions(
            ['price'],
            FilterComparator.CONTAINS_STRING,
            '3',
            MatchType.ANY,
            true
        );

        this.containsStringFilterOptions.variableMappers = [ 
            (item: any) => {
                return this.convertItemPriceToCurrencyString(item);
            }
        ];

        let filteredValues: any[] = this.filterSortService.filterAndSortItems(
            this.items,
            this.containsStringFilterOptions,
            null
        );
        console.log(filteredValues); // filteredValues = [{price: 342.07}];
    }

    convertItemPriceToCurrencyString(item: any): string {
        return '$' + (item.price).toString();
    }
}


Filtering with Multiple FilterOptions:

Below is a Typescript implementation that filters a set of objects between a range of 20 to 25.

import {FilterOptions, FilterComparator, FilterSortService} from '@tablejs/community';

export class MultipleFilterOptions implements OnInit {
    prices: any[] = [{price: 342.07}, {price: 12.19}, {price: 45.59}, {price: 21.00}];
    lessThanOrEqualFilterOptions: FilterOptions;
    greaterThanOrEqualFilterOptions: FilterOptions;
    
    constructor(private filterSortService: FilterSortService) {
        this.filterBetween20and25();
    }

    filterBetween20and25(): void {
        this.lessThanOrEqualFilterOptions = new FilterOptions(
            ['price'],
            FilterComparator.LESS_THAN_OR_EQUAL,
            25,
            MatchType.ANY,
            true
        );

        this.greaterThanOrEqualFilterOptions = new FilterOptions(
            ['price'],
            FilterComparator.GREATER_THAN_OR_EQUAL,
            20,
            MatchType.ANY,
            true
        );

        let filteredPurchases: any[] = this.filterSortService.filterAndSortItems(
            this.prices,
            [this.lessThanOrEqualFilterOptions, this.greaterThanOrEqualFilterOptions],
            null
        );
        console.log(filteredPurchases); // filteredPurchases = [{price: 21.00}]
    }
}


Classes

Range

Version Available: 1.2.0 or higher, 2.0.0 or higher

import { Range } from '@tablejs/community';

Description:

The item index range the ScrollViewportDirective is rendering in the viewport

Properties:

Property Description
startIndex:
number
The index of the first item visible in the ScrollViewportDirective
endIndex:
number
The index of the last item visible in the ScrollViewportDirective
extendedStartIndex:
number
The index of the first item rendered by the ScrollViewportDirective
extendedEndIndex:
number
The index of the last item rendered by the ScrollViewportDirective


Usage:

See ScrollViewportEvent

SortComparator

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { SortComparator } from '@tablejs/community';

Description:

Extends the Comparator class. Contains static comparator functions for use in sorting arrays.

Methods:

Method
DATE
[static] A comparator function for sorting items by date
Parameters
valueA: any
valueB: any
Returns
number


Method
NUMERIC
[static] A comparator function for sorting items in numeric order
Parameters
valueA: any
valueB: any
Returns
number


Method
BOOLEAN
[static] A comparator function for sorting items by boolean values
Parameters
valueA: any
valueB: any
Returns
number


Method
TRUTHY
[static] A comparator function for sorting items by truthy
Parameters
valueA: any
valueB: any
Returns
number


Method
ALPHABETICAL
[static] A comparator function for sorting items in alphabetical order
Parameters
valueA: any
valueB: any
Returns
number


Method
triggerNoSortOptionsError
[static] A function that throws an error when a SortOptions object is not supplied.
Returns
void


Usage:

See SortOptions

SortOptions

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { SortOptions } from '@tablejs/community';

Description:

A set of sorting options used for sorting an array of items. Implements ISortOptions.

Properties:

Property Description
id : string An identifier for this set of options.
variableIdentifier : string | null | undefined A property or array of property identifiers used to determine the value from an item that should be sorted (ex: 'name' returns the value of item.name)
initialSortDirection : number | SortDirection.DESCENDING | SortDirection.NONE | SortDirection.ASCENDING Holds the initial sort direction.
ignoreCase : boolean Option to ignore case-sensitivity.
ignoreTimeOfDay : boolean Option to ignore the time of day when comparing Date objects.
sortOrder : number Indicates the order in which the FilterSortService will filter this SortOptions object in relation to the other SortOptions objects that are supplied to the FilterSortService.filterAndSortItems function.
comparator :
(valueA: any, valueB: any) => number
A function used for comparing values. If the function returns < 0, valueA will sort before valueB. If the function returns > 0, valueA will sort after valueB. If the function returns 0, the order will remain unchanged between the two values.
variableMapper? : Function | null [Optional] Function(s) used to modify values of an item before it is ordered.
useLocaleCompare : boolean Sorts a string based on a locale’s sorting rules. See localeCompare.
localeCompareOptions : [string | string[]] | [string | string[], Intl.CollatorOptions] | null Options provided for useLocaleCompare sorting. See localeCompare.
directionOrder : (number | SortDirection.ASCENDING | SortDirection.DESCENDING | SortDirection.NONE)[] The order in which the SortOptions will sort in when the SortOptions.nextSortDirection() function is called.
sortDirection : number | SortDirection.ASCENDING | SortDirection.DESCENDING | SortDirection.NONE The current sorting direction of the SortOptions object.


Methods:

Property Description
nextSortDirection (): void Changes the sort direction to the next SortDirection value in the directionOrder array. If the direction is the last SortDirection in the array, the SortOptions will revert to the first SortDirection in the directionOrder array.


Usage:

Sorting with a Single SortOptions

In the Typescript example below, we are sorting the purchases array numerically and in ascending order.

import {SortOptions, SortComparator, FilterSortService} from '@tablejs/community';

export class NextSortingDirection implements OnInit {
    priceSortOptions: SortOptions;
    purchases: any[] = [{price: 342.07}, {price: 12.19}, {price: 45.77}, {price: 12.06}];

    constructor(public filterSortService: FilterSortService) {
        this.setSortOptions();
        this.sortPurchasesByPrice();
    }

    setSortOptions(): void {
        this.priceSortOptions = new SortOptions(
            'price',
            SortComparator.NUMERIC,
            SortDirection.NONE
        );
    }

    sortPurchasesByPrice(): void {
        this.priceSortOptions.nextSortDirection();

        let sortedPurchases: any[] = this.filterSortService.filterAndSortItems(
            this.purchases,
            null,
            this.priceSortOptions
        );
        console.log(sortedPurchases); // sortedPurchases = [{price: 12.06}, {price: 12.19}, {price: 45.77}, {price: 342.07}]
    }
}


Sorting with Multiple SortOptions

In the Typescript example below, the purchases are sorted by name, item, and price.

import {SortOptions, SortComparator, FilterSortService} from '@tablejs/community';

export class SortOrder implements OnInit {
    priceSortOptions: SortOptions;
    nameSortOptions: SortOptions;
    itemSortOptions: SortOptions;

    purchases: any[] = [
        {name: 'adam', item: 'action figure', price: 342.07}, 
        {name: 'kyle', item: 'comic book', price: 12.19}, 
        {name: 'bill', item: 'video game', price: 60}, 
        {name: 'jill', item: 'bracelet', price: 12.06}
    ];

    constructor(private filterSortService: FilterSortService) {
        this.setSortOptions();
        this.sortPurchasesByNameItemAndPrice();
    }

    setSortOptions(): void {
        this.nameSortOptions = new SortOptions(
            'name',
            SortComparator.ALPHABETICAL,
            SortDirection.NONE
        );
        this.itemSortOptions = new SortOptions(
            'item',
            SortComparator.ALPHABETICAL,
            SortDirection.DESCENDING
        );
        this.priceSortOptions = new SortOptions(
            'price',
            SortComparator.NUMERIC,
            SortDirection.NONE
        );
    }

    sortPurchasesByNameItemAndPrice(): void {
        this.nameSortOptions.nextSortDirection();
        this.itemSortOptions.nextSortDirection();
        this.priceSortOptions.nextSortDirection();

        let sortedPurchases: any[] = this.filterSortService.filterAndSortItems(
            this.purchases,
            null,
            [this.nameSortOptions, this.itemSortOptions, this.priceSortOptions]
        );
        console.log(sortedPurchases);
        // [{name: 'jill', item: 'bracelet', price: 12.06},
        // {name: 'kyle', item: 'comic book', price: 12.19},
        // {name: 'bill', item: 'video game', price: 60},
        // {name: 'adam', item: 'action figure', price: 342.07}]
                                     
    }
}


TablejsForOfContext

Version Available: 1.4.9 or higher, 2.1.9 or higher

import { TablejsVirtualForOf } from '@tablejs/community';

Description:

The context object the TablejsForOf will use to render a single row.

Properties:

Property Description
first ():
boolean
[read-only] Returns whether the context pertains to the first item in the tablejsVirtualFor list.
last ():
boolean
[read-only] Returns whether the context pertains to the last item in the tablejsVirtualFor list.
even ():
boolean
[read-only] Returns whether the context pertains to an item which has an even-numbered index in the tablejsVirtualFor list.
odd ():
boolean
[read-only] Returns whether the context pertains to an item which has an odd-numbered index in the tablejsVirtualFor list.

IAbstractOptions

Version Available: 1.3.0 or higher, 2.0.0 or higher

import { MatchType } from '@tablejs/community';

Description:

Provides an abstract class for creating sort and filter options

Properties:

Property Description
id: string An identifier for a particular set of options
ignoreCase: boolean A value to signify whether an option should ignore case-sensitivity
ignoreTimeOfDay: boolean A value to signify whether an option should ignore the time of day when matching against a Date


Usage:

See ISortOptions and IFilterOptions

IColumnHideChange

import { IColumnHideChange } from '@tablejs/community';

Description:

Provides a structure for column hide state changes. See GridDirective.hiddenColumnChanges()

Properties:

Property Description
hierarchyColumn : IColumnHierarchy The IColumnHierarchy related to the change in column visibility.
hidden : boolean Indicates whether the column visibility was set to hidden.
wasTriggeredByThisColumn : boolean If true, the visibility of this column was triggered by this column. If false, the visibility for this column was triggered by another column’s visibility changing.

IColumnHierarchy

import { IColumnHierarchy } from '@tablejs/community';

Description:

Provides a structured hierarchy for nested columns. Columns are organized in a tree-like structure. Nested columns branch from columns of higher hierarchical prominence.

Properties:

Property Description
level : number Provides a hierarchical level for a column. The lower the number, the higher the hierarchical prominence.
element : Element The th element pertaining to this IColumnHierarchy.
parent : Element Current parent element of the specified element.
parentColumn : Element The th element that pertains to one level up in the column hierarchy. The element would be a branch of parentColumn element.
subColumns : IColumnHierarchy[] The list of IColumnHierarchy column data that are branches of this IColumnHierarchy.

Interfaces

IFilterOptions

import { IFilterOptions } from '@tablejs/community';

Description:

Provides a structure for filter options. Extends IAbstractOptions.

Properties:

Property Description
variableIdentifiers:
string | string[]
A property or array of property identifiers used to determine the value from an item that should be filtered (ex: 'name' returns the value of item.name)
comparator:
(element: any, index: number, array: any[]) => boolean
A function used for comparing values. If the function returns true, the item will be pushed into the filtered array. A false return value will exclude the compared item from the filtered array
variableMappers?:
Function | Function[]
Optional Function(s) that will modify the value(s) of an item before it is filtered. Filtering comparison will occur on the modified value
filterValue:
Function | Function[]
The value by which all filtering should be compared
matchType:
string | MatchType.ALL | MatchType.ANY
A match type to determine whether a comparator function requires a single identifier to match the filterValue or all identifiers


Usage

See FilterOptions

ISortOptions

import { ISortOptions } from '@tablejs/community';

Description:

Provides a structure for sort options. Extends IAbstractOptions.

Properties:

Property Description
variableIdentifier:
string
A property used to determine the value from an item that should be sorted (ex: 'name' returns the value of item.name)
comparator:
(valueA: any, valueB: any) => number
A function used for comparing values. A negative return value will sort valueA before valueB. A positive return value will sort valueA after valueB. A return value of 0 keeps the current order intact
variableMapper?:
Function | Function[]
Optional Function that will modify the value of an item before it is sorted. Sort comparison will occur on the modified value
initialSortDirection:
number | SortDirection.DESCENDING | SortDirection.NONE | SortDirection.ASCENDING
The starting sort direction. Defaults to SortDirection.NONE
sortOrder: number The order placement in which the set of sort options will will be sorted
useLocaleCompare: boolean Toggles whether to use locale comparison. See String.localeCompare
localeCompareOptions:
[string | string[]] | [string | string[], Intl.CollatorOptions]
Options given for a locale comparison. See Intl.CollatorOptions
directionOrder:
(number | SortDirection.ASCENDING | SortDirection.DESCENDING | SortDirection.NONE)[]
The order of directions in which the options should sort.
sortDirection:
number | SortDirection.DESCENDING | SortDirection.NONE | SortDirection.ASCENDING
The current sort direction of the options


Usage:

See SortOptions

Namespaces

MatchType

import { MatchType } from '@tablejs/community';

Description:

Provides options for filtering items by matching single or all values.

Public Constants:

Property Description
ALL: string = ‘all’ A static option for defining filtering matches based on all values
ANY: string = ‘any’ A static option for defining filtering matches based on a single value


Usage:

See FilterOptions

SortDirection

import { SortDirection } from '@tablejs/community';

Description:

Provides options for defining sort direction

Public Constants:

Property Description
DESCENDING: number = -1 A static option for defining a descending direction for sorting
NONE: number = 0 A static option for defining no sort direction for sorting
ASCENDING: number = 1 A static option for defining an ascending direction for sorting


Usage:

See SortOptions