ParamQuery Grid (free version) Tutorial

A Word about its design

ParamQuery Grid keeps its data and view separate (literally). And it has two display modes: Virtual and non - virtual mode. Non - virtual mode is the default mode whereby all the rows and columns are displayed at once in the viewport. While in virtual mode or performance mode, it displays or renders only the rows and columns which fit in its scrollable viewport. It's the virtual mode that empowers grid to display unlimited rows and columns. It can be enabled simply by setting the options virtualX ( for columns virtualization ) and virtualY ( for rows virtualization ) to true. Grid refreshes its view ( and refresh event is fired ) whenever the following takes place:

  • View is scrolled either horizontally or vertically. ( virtual mode )
  • Any paging event. ( virtual & non-virtual mode )
  • Any sorting event. ( virtual & non-virtual mode )
  • Any resize event. ( virtual & non-virtual mode )
  • refresh(), refreshView() or refreshDataAndView() is invoked. ( virtual & non-virtual mode )

ParamQuery Grid stores data for both local & remote requests in which is a 2 dimensional array or JSON (array of key/value paired objects). It refreshes its local copy of data for remote requests whenever the following takes place:

  • Remote paging.
  • Remote sorting.
  • Remote filtering.
  • refreshDataAndView() is invoked. can be manipulated directly for both local and remote requests.
refreshDataAndView() is invoked usually after direct manipulation of dataModel properties to put the data and view in sync. refresh() is invoked usually after modification of the grid DOM.

ParamQuery includes 3 independent jQueryUI widgets/components : pqPager, pqScrollBar and pqSelect. pqPager has class pq-pager, hence reference to pqPager inside the grid can be obtained using $( ".pq-pager", $grid ).pqPager(). Similarly reference to vertical and horizontal scrollbars can be obtained by $( ".pq-sb-vert", $grid ).pqScrollBar() & $( ".pq-sb-horiz", $grid ).pqScrollBar() respectively.

Include Files

If you use ParamQuery with npm then you may skip to next section.

To use ParamQuery without npm first of all include these js and css files in the header section of the web page.

Any version of jQuery can be used but jQueryUI version should be 1.11.4+

jQueryUI 1.11.4

<!--jQuery dependency, any stable version of jQuery-->    
    <script src="[email protected]/dist/jquery.js"></script>    

<!--jQueryUI version 1.11.4 -->
    <link rel="stylesheet" href="" />
    <script src=""></script>

<!--ParamQuery Grid css files-->
    <link rel="stylesheet" href="path to pqgrid.(min/dev).css" />    

    <!--add pqgrid.ui.css for jQueryUI theme support-->
    <link rel="stylesheet" href="path to pqgrid.ui.(min/dev).css" />

    <!--ParamQuery Grid custom theme e.g., office, bootstrap, rosy, chocolate, etc (optional)-->
    <link rel="stylesheet" href="path to custom theme pqgrid.css" />

<!--Include jsZip file (v2.5.0) before pqgrid js file to support xlsx and zip export (optional)-->
    <script type="text/javascript" src="path to jsZip.js" ></script>   

<!--ParamQuery Grid js files-->
    <script type="text/javascript" src="path to pqgrid.(min/dev).js" ></script>   

    <!--ParamQuery Grid localization file-->
    <script src="localize/pq-localize-xx.js"></script>

<!--Include pqTouch file to provide support for touch devices (optional)-->
    <script type="text/javascript" src="path to pqtouch.min.js" ></script>   

Sample jsfiddle

jQueryUI 1.12

<!--jQuery dependency, any stable version of jQuery-->    
    <script src="[email protected]/dist/jquery.js"></script>    

<!--jQueryUI version 1.12 -->
    <link href="[email protected]/jquery-ui.css" rel="stylesheet" />
    <link href="[email protected]/jquery-ui.structure.css" rel="stylesheet" />
    <link href="[email protected]/jquery-ui.theme.css" rel="stylesheet" />
    <script src="[email protected]/jquery-ui.js"></script>

<!--ParamQuery Grid css files-->
    <link rel="stylesheet" href="path to pqgrid.(min/dev).css" />    

    <!--add pqgrid.ui.css for jQueryUI theme support-->
    <link rel="stylesheet" href="path to pqgrid.ui.(min/dev).css" />

    <!--ParamQuery Grid custom theme e.g., office, bootstrap, rosy, chocolate, etc (optional)-->
    <link rel="stylesheet" href="path to custom theme pqgrid.css" />

<!--Include jsZip file (v2.5.0) before pqgrid js file to support xlsx and zip export (optional)-->
    <script type="text/javascript" src="path to jsZip.js" ></script>   

<!--ParamQuery Grid js files-->
    <script type="text/javascript" src="path to pqgrid.(min/dev).js" ></script>   

    <!--ParamQuery Grid localization file-->
    <script src="localize/pq-localize-xx.js"></script>

<!--Include pqTouch file to provide support for touch devices (optional)-->
    <script type="text/javascript" src="path to pqtouch.min.js" ></script>   

Sample stackblitz

jQuery, jQueryui dependency files can either point to CDN repositories (recommended) or they can point to the files kept on server locally.

Compatibility chart between jQuery and jQueryUI

v1.x.x, v2.x.xv1.11.4, v1.12.x

NPM Package

Free version of pqgrid can be installed though a nodejs package manager e.g, npm or yarn.

npm i pqgridf

pqgridf has following peer dependencies which can also be installed through a package manager.


Dependencies are kept as peer dependencies for efficiency, though you can make them private dependencies by editing package.json file inside pqgrid package if there is any version conflict with any other package. e.g, pqgrid is dependent upon version 2.5 of jsZip and if there is any other package in your project with peer dependency on jsZip any other version, then you can make jsZip a private dependency either in pqgrid or that other package.

pqgridf exports pq module which is imported into your application by

import pq from 'pqgridf';

All css files for pqgridf and dependencies are included in styles.css ( for Angular ) using @import

/* Add application styles & imports to this file! */
@import '~jquery-ui-pack/jquery-ui.css';
@import '~jquery-ui-pack/jquery-ui.structure.css';

@import '~jquery-ui-pack/jquery-ui.theme.css';

@import '~pqgridf/pqgrid.min.css';
@import '~pqgridf/pqgrid.ui.min.css';
@import '~pqgridf/themes/steelblue/pqgrid.css';

Create First ParamQuery Grid

Within the jQuery ready function, initialize the grid as $( ".selector" ).pqGrid( obj ); where obj is a PlainObject passed to the pqGrid constructor function.

obj provides information about width, height, columns information, data, location and type of data, etc.

colModel and dataModel are the 2 main keys of information in the obj.

As their names indicate, the main role of dataModel is to provide data and data related information to the grid whereas colModel provides information specific to the columns i.e titles, widths, data type (used for sorting), etc. Please check API section to see the comprehensive list of options which can be used in obj, dataModel and colModel.


    //JSON data (array of objects) can be defined locally 
    //or might be a response from an AJAX call from web server/service.
    var data = [
        { rank: 1, company: 'Exxon Mobil', revenues: 339938.0, profits: 36130.0 },
        { rank: 2, company: 'Wal-Mart Stores', revenues: 315654.0, profits: 11231.0 },
        { rank: 3, company: 'Royal Dutch Shell', revenues: 306731.0, profits: 25311.0 },
        { rank: 4, company: 'BP', revenues: 267600.0, profits: 22341.0 },
        { rank: 5, company: 'General Motors', revenues: 192604.0, profits: -10567.0 },
        { rank: 6, company: 'Chevron', revenues: 189481.0, profits: 14099.0 },
        { rank: 7, company: 'DaimlerChrysler', revenues: 186106.3, profits: 3536.3 },
        { rank: 8, company: 'Toyota Motor', revenues: 185805.0, profits: 12119.6 },
        { rank: 9, company: 'Ford Motor', revenues: 177210.0, profits: 2024.0 },
        { rank: 10, company: 'ConocoPhillips', revenues: 166683.0, profits: 13529.0 },
        { rank: 11, company: 'General Electric', revenues: 157153.0, profits: 16353.0 },
        { rank: 12, company: 'Total', revenues: 152360.7, profits: 15250.0 },
        { rank: 13, company: 'ING Group', revenues: 138235.3, profits: 8958.9 },
        { rank: 14, company: 'Citigroup', revenues: 131045.0, profits: 24589.0 },
        { rank: 15, company: 'AXA', revenues: 129839.2, profits: 5186.5 },
        { rank: 16, company: 'Allianz', revenues: 121406.0, profits: 5442.4 },
        { rank: 17, company: 'Volkswagen', revenues: 118376.6, profits: 1391.7 },
        { rank: 18, company: 'Fortis', revenues: 112351.4, profits: 4896.3 },
        { rank: 19, company: 'Crédit Agricole', revenues: 110764.6, profits: 7434.3 },
        { rank: 20, company: 'American Intl. Group', revenues: 108905.0, profits: 10477.0 }
    //array of columns.
    var colModel = [
            title: "Rank", //title of column. 
            width: 100, //initial width of column
            dataType: "integer", //data type of column
            dataIndx: "rank" //should match one of the keys in row data.
            title: "Company", 
            width: 200, 
            dataType: "string", 
            dataIndx: "company" 
            title: "Revenues ($ millions)", 
            width: 150, 
            dataType: "float", 
            align: "right", 
            dataIndx: "revenues" 
            title: "Profits ($ millions)", 
            width: 150, 
            dataType: "float", 
            align: "right", 
            dataIndx: "profits" 

    //main object to be passed to pqGrid constructor.    
    var obj = {
        width: 700, //width of grid
        height: 400, //height of grid
        colModel: colModel,
        dataModel: {data: data}

    $("#grid_json").pqGrid( obj );                                

In the body tag define the div tag/tags which act as placeholders for the grid.

<div id="grid_json"></div>

How to load data

There exist a number of ways to load data in pqGrid which are based on open standards & RESTful architecture. At a top level, these can be categorized into 2 cases depending upon value of dataModel.location.

Case I: dataModel.location = 'local';

When dataModel.location is local, it's the responsibility of implementor to assign data to the grid manually i.e., $grid.pqGrid( 'option', '', data); where data is in format of array of rows. dataModel.location = 'local' doesn't necessarily mean local data. The data can reside locally in the browser within script tags or could be fetched from remote web server / service using synchronous or asynchronous AJAX calls. Assignment of data to grid is usually followed by a call to refreshDataAndView() in order to process and render data in the grid. Remote paging, remote sorting and remote filtering are bit tedious to implement when dataModel.location is local.

Case II: dataModel.location = 'remote';

When dataModel.location is remote, grid loads data on its own from remote location. There is no need to manually make an AJAX call and assign data to dataModel. In this case number of options have to be provided to pqGrid i.e., dataModel.url / dataModel.getUrl, dataModel.getData, dataModel.dataType, dataModel.method etc. When dataModel.url is provided, Grid constructs the query strings ( for GET requests ) or POST data on its own and send fields to the remote server having pq_ prefix e.g. pq_curpage, pq_rpp, etc. In some cases when more control is required over query strings / POST data sent to server, implementor may decide to construct these parameters on his own by implementing dataModel.getUrl callback. In some other cases, it's merely required to add/append rather than replace more bits of information to the fields send by pqGrid to server. As such it's prudent to use dataModel.postData and dataModel.postDataOnce options. dataModel.getData callback acts as a sieve to separate wheat from chaff. In pqGrid's context chaff is the response received from the server and wheat is the useful and acceptable data pieces for the grid. refreshDataAndView() is called manually or automatically by the grid whenever reload / refresh of data from remote server is required. Local paging, local sorting and local filtering can be implemented even when dataModel.location is remote.

Remote requests

For remote paging, filtering & sorting, the grid sends the following fields of information to the server as GET or POST requests. By default the fields are serialized to string with JSON.stringify before sending it to the server. Serialization can be turned off by setting stringify option of pqGrid to false.

TypeRequest variables
Name Value
Paging pq_datatype dataModel.dataType
pq_curpage pageModel.curPage
pq_rpp pageModel.rPP
Sorting pq_datatype dataModel.dataType
pq_sort sortModel.sorter e.g.,
pq_sort: [{"dataIndx":"ShipCountry","dir":"up"}, {"dataIndx":"ContactName","dir":"down"}]
Filtering pq_datatype dataModel.dataType
pq_filter Object variable having fields named "mode" and "data". The value of "mode" is taken from filterModel.mode and "data" is an array of objects constructed from individual column.filter e.g.,
pq_filter: { "mode": "AND", "data": [{"dataIndx":"ShipCountry","value":"fr","condition":"begin"}, {"dataIndx":"ContactName","value":"pa","condition":"begin"}]}

Using jQueryUI themes

Any jQueryUI theme can be used by replacing base with the name of desired theme in the above lists of jQuery dependencies. The following is a list of ready to use 24 jQueryUI themes:

  • base
  • black-tie
  • blitzer
  • cupertino
  • dark-hive
  • dot-luv
  • eggplant
  • excite-bike
  • hot-sneaks
  • humanity
  • le-frog
  • mint-choc
  • overcast
  • pepper-grinder
  • redmond
  • south-street
  • start
  • smoothness
  • sunny
  • swanky-purse
  • trontastic
  • ui-darkness
  • ui-lightness
  • vader

For example to use Redmond theme, include the below file (if pointing to CDN repositories):

<link rel="stylesheet" 
    href="" />
instead of

<link rel="stylesheet" 
    href="" />
To create your own custom theme or even to customize any of the above themes, visit here

Style alternate rows in jQueryUI themes

There is lack of appropriate class to style alternate rows in jQueryUI themes. However custom color/style to alternate rows can be added with the below rule

.pq-grid-oddRow > td{
    /* add your styles here */

Using jQueryUI and custom icons

Icons are used at many places in the grid e.g. in toolbar, pager, grouping icons, etc. ParamQuery Grid is jQuery theme ready and hence relies upon jQueryUI icons. Reference to a list of all jQuery icons can be obtained from and icon class names can be gathered by hovering mouse over the icons. The icon class names can be used in API of the grid.

If jQueryui icons don't satisfy your taste or need, you can create your own icons of dimensions 16px x 16px, use them in CSS classes and assign those class names to applicable parameters in API of the grid.

Significance of

The grid data is stored in in the form of an array of rows. When we use local paging, contains all the data of all the pages. But when we use remote paging, contains only the data on current page. In the latter case, is refreshed every time we move from page to page or we hit refresh button in the pager.

Special Variable Names

These are some of the variable names used in API and examples which are named so by convention.

$grid is the name of jQuery object that refers to grid container div.

            var $grid = $( ".selector" ); // e.g., $( "#grid_json" );

            //it can also be obtained from inside event callback functions.
            var $grid = $( ).closest( '.pq-grid' );

            //it can also be obtained from grid variable.
            var $grid = grid.widget();
All pqgrid methods can be called with this variable as
            $grid.pqGrid( 'method_name', parameters );

grid is the name of javascript object that refers to a live instance of pqGrid.
            var grid = pq.grid( "#grid_json", options ); //constructor (>= v3.2.0)

            //it can also be obtained from $grid variable as.
            var grid = $grid.pqGrid('instance'); //jQueryUI >= v1.11

            var grid = $grid.pqGrid('getInstance').grid;

            //can also be obtained directly from context of event callback functions.
            var grid = this;
All pqgrid methods can be called with this variable as
            grid.method_name( parameters );

rowIndx is zero based index of a row relative to page 1, row 1. So first row has rowIndx = 0, 2nd row has rowIndx = 1 and so on. It's easy to get reference to a row data if rowIndx is known. For example if we need a reference to 50th row, we can simply get it as var rowData =[49]; where 49 is rowIndx of 50th row. It would work the same whether we use local paging, remote paging or no paging at all.

rowIndxPage is zero based index of a row relative to the current page. There are number of instances when rowIndxPage is easier to use as compared to rowIndx e.g., while inserting a new row on the current page. Also when we use remote paging, rowIndxPage makes better sense as contains data on current page only.

We require records per page and current page number when we wish to calculate rowIndxPage from rowIndx and vice versa. For example if there are 20 rows per page and we are currently on page 3, then rowIndxPage of the row (whose rowIndx is 49) is 9. To save oneself from the trouble of doing the calculations, most of the methods accept rowIndx or rowIndxPage as argument. Similarly most of the events provide rowIndx or rowIndxPage as parameters to be utilized in callback functions.

rowData signifies data for a row, it is extracted from the grid data by[ indx ] where indx is substituted by rowIndx in case of local data, while rowIndxPage in case of remote paging.

dataIndx is the name of field/key in JSON data or numeric index of field in array data. A field or cell value can be obtained from row data by rowData[ dataIndx ].

colIndx is zero based numeric index of column in colModel array. column and hence its properties can be accessed from colModel as colModel[ colIndx ]. It also signifies the physical order of a column, so column with colIndx of 0 is at the leftmost corner of the grid and so on.

Call pq methods

There are 2 different syntactic ways to call pq methods having same end result:

  1. First one is the use of widget name $( ".selector" ).widgetName( 'method_name', parameters ); e.g., $grid.pqGrid( 'refreshRow', { rowIndx: 2} ) where $grid is the jQuery object wrapped on grid container DOM element. This one is safer ( in the sense it prevents accidental or intentional calling of pqGrid private methods ) but it's verbose, bit slower and garbles up the call stack with intermediate calls to jQueryUI framework.

    This way of method calling is used for jQuery only.

  2. Second one is use of widget instance instance.method_name( parameters ) e.g., grid.refreshRow( { rowIndx: 2 } ) where grid is a live instance of pqGrid. This one is faster and concise.

    This way of method calling is used for Angular, jQuery, React or Vue.

Use pq events

PQ has a powerful event system to inform about interesting points in the lifecycle of widget.

Event listeners are implemented by writing a callback function that is called by the widget when the specified event occurs. Every event listener function has 2 arguments: event and ui where

  • event is an object that provides information about the event in terms of type of event, target, currentTarget, coordinates (pageX, pageY, etc) of the event in case of keyboard or mouse event,
  • ui is an object that provides information about grid specific properties, e.g., rowIndx, rowData, colIndx, dataIndx, etc.

There are 3 ways to bind pq events.

  • 1st and 2nd ways can be used with Angular, jQuery, plain js, React and Vue
  • 3rd one is for use with jQuery only.
  1. Use callback options while initialization i.e.,
                    pq.grid( selector, {                     
                        beforeSort: function( evt, ui ){
                            //code here 
                        //other options.
    or set options after initialization i.e.,
                    grid.option( "beforeSort", function( evt, ui ){
                        //code here 
    This one is fast and easy way to listen to events but has limitation of one callback per event and can't listen to bubbled events.

  2. Use instance listeners that are bound directly to instance of widget. For example to listen to beforeSort event, it's
                grid.on( "beforeSort", function( evt, ui ){
                    //code here.
    Multiple event listeners can be implemented and multiple events can be specified in a single call by specifying space separated list of events. one and off are also supported for instance listeners. This is also easy and quick way of binding event listeners but these can't be used to listen to bubbled events. If more than one listener is implemented for a single event, they are called in the same order as they are added.

  3. Bind event listeners to DOM elements with jQuery API.
                $( ".selector" ).on( "pqGrid:beforeSort", function( evt, ui ){
                    //code here.
    It's disabled by default for performance reasons. It can be turned on by setting trigger option to true.

DOM events and bubbling ( applicable to jQuery/ plain js only ): By default the PQ events are not emitted to DOM elements since v3.2.0 which if required can be turned on by specifying trigger option in the widget to true. The events also don't bubble by default since v3.2.0. Consider case of nested grids where event listener is bound to outer grid for some event; when same event is emitted by inner grid event bubbling leads to invocation of event listener of the outer grid. This can lead to issues unless we are careful to check the currentTarget of event. Again if required, bubbling can be turned on by setting option bubble to true.

Order of events: When more than one event listener for a single event are implemented together, the event listeners are called in this order:

instance listeners > DOM event listeners > callback option.

It's possible to call stopImmediatePropagation() on the event object to stop further handling of the event by other pending listeners. It's also possible to stop further propagation to parent handlers or bubbling of event by returning false or calling stopPropagation() on the event object.

Context of events: The context ( i.e., this variable ) is instance of the grid inside callback options ( 1st way ) and instance listeners ( 2nd way ), while it's a reference to DOM element of the widget inside DOM event listeners ( 3rd way ).

Summary of differences between versions:

Feature version < v3.2.0 version >= v3.2.0
Instance listeners Not available. Available
Event type widgetName + "event name" all in lowercase e.g., pqgridbeforesort widgetName+":event name" e.g., pqGrid:beforeSort
Context i.e., this of callback options and instance listeners DOM element of the widget instance of the widget in instance listeners while DOM element of the widget in DOM event listeners
Bubbling and emission of events on DOM nodes true by default false by default

How to refresh the data or view of grid

pqGrid tries to refresh view on its own prior to version 2.0.2 in most cases when dataModel properties are changed. This behaviour is sometimes undesirable e.g. consecutive calls to API changing dataModel properties may lead to undesirable refreshes and reloads of data which is not good for performance. This has changed starting from 2.0.2 whereby the data or view of grid can be refreshed in a more controlled manner. pqGrid can be refreshed in various ways depending upon what or which part of the grid needs to be refreshed. Please see the below comparison table to know which method to use:

refresh refreshView refreshDataAndView
Refresh Column Header Yes Yes Yes
Refresh view for updated rows Yes Yes Yes
Refresh view for added rows No Yes Yes
Refresh view for removed rows No Yes Yes
Reload data from server (location = 'remote') No No Yes
Reload data from (location = 'local') - Yes Yes
Refresh local paging No Yes Yes
Refresh local sorting No No Yes
Refresh local filtering No No Yes
Refresh row grouping No Yes Yes

Performance tips

If you are updating lot of rows let's say hundreds or thousands of them with API methods such as updateRow, addClass, removeClass, attr, removeAttr, the grid is bound to get slow because the view is refreshed by these methods by default and DOM updates are inherently slow. In order to prevent refresh of view with each method call, refresh parameter to these methods can be passed as false and one final consolidated refresh can be done with a call to refresh method in the end.

Same logic can be applied to other methods in the API which cause a view refresh e.g., addRow, deleteRow. These methods also accept refresh as parameter which can be passed as false. But instead of refresh, these require refreshView in the end because these methods change the number of rows.

There are few callbacks such as column.render & rowInit in which view refresh is not required and is unnecessary waste of resources. These callbacks are invoked at a time when view of the grid is being prepared and refresh of the view is anyway due after these callbacks. So for performance sake it's prudent to pass refresh: false as parameters if any of these methods addClass, removeClass, attr, removeAttr are called from these callbacks.

How to change locale of a grid / grids

  • The below mentioned lines of code would change the locale of all pqGrid instances in the whole document. These lines should be added after the paramquery grid and localization js files are loaded but before initialization of pqGrid.
        $.extend($.paramquery.pqGrid.prototype.options, $.paramquery.pqGrid.regional[locale]);
        $.extend($.paramquery.pqPager.prototype.options, $.paramquery.pqPager.regional[locale]);
    where locale is to be substituted with the locale name.
    For example if it's desired to change the locale to japanese, pq-localize-ja.js file should be included in the page and the below two lines should be added.
        $.extend($.paramquery.pqGrid.prototype.options, $.paramquery.pqGrid.regional['ja']);
        $.extend($.paramquery.pqPager.prototype.options, $.paramquery.pqPager.regional['ja']);

  • If it's required to change locale or localization strings for only one grid amongst many grids in the same HTML document/ web page without affecting other grids e.g., one grid may be in Spanish, second in Japanese, etc., put the below lines after initialization of that particular grid.
        $grid.pqGrid("option", $.paramquery.pqGrid.regional[locale]);
        $grid.find(".pq-pager").pqPager("option", $.paramquery.pqPager.regional[locale]);

  • Any particular localization string or strings for a particular grid can be set or changed just like normal options. The list of localization string options can be obtained from localization file. e.g.,
        $grid.pqGrid({ strNoRows : 'No Rows found.' });
        $grid.pqGrid( 'option', { strNoRows : 'No Rows found.' });

Further Reading

How to use jQuery UI widgets