Grid Column Pinning

A column or multiple columns can be pinned to the left-hand side of the Angular UI Grid. Column Pinning in Ignite UI for Angular allows the end users to lock column in a particular column order, this will allow them to see it while horizontally scrolling the Grid. The Material UI Grid has a built-in column pinning UI, which can be used through the Grid's toolbar to change the pin state of the columns. In addition, you can define a custom UI and change the pin state of the columns via the Column Pinning API.

Demo


Column Pinning API

Each column can be pinned, as long as the pinned area does not become wider than the Grid itself. Column pinning is controlled through the pinned input of the igx-column. Pinned columns are always rendered on the left side of the Grid and stay fixed through horizontal scrolling of the unpinned columns in the Grid body.

<igx-grid #grid1 [data]="data | async" [width]="700px" [autoGenerate]="false" [paging]="true" [perPage]="6" (onColumnInit)="initColumns($event)"
    (onSelection)="selectCell($event)">
    <igx-column [field]="Name" [pinned]="true"></igx-column>
    <igx-column [field]="AthleteNumber"></igx-column>
    <igx-column [field]="TrackProgress"></igx-column>
</igx-grid>

You may also use the Grid's pinColumn or unpinColumn methods of the IgxGridComponent to pin or unpin columns by their field name:

this.grid.pinColumn("AthleteNumber");
this.grid.unpinColumn("Name");

Both methods return a boolean value indicating whether their respective operation is successful or not. Usually the reason they fail is that the column is already in the desired state. pinColumn also fails when the result would mean that the pinned area becomes larger than or the same size as the Grid itself. Consider the following example:

<igx-grid #grid1 [data]="data | async" [width]="300px" [autoGenerate]="false">
    <igx-column [field]="Name" [width]="200px" [pinned]="true"></igx-column>
    <igx-column [field]="AthleteNumber" [width]="200px"></igx-column>
</igx-grid>
var succeed = this.grid.pinColumn("AthleteNumber"); // pinning fails and succeed will be false

If pinning the AthleteNumber column is allowed the pinned area would exceed the Grid's width.

A column is pinned to the right of the rightmost pinned column. Changing the order of the pinned columns can be done by subscribing to the onColumnPinning event and changing the insertAtIndex property of the event arguments to the desired position index.

<igx-grid #grid1 [data]="data | async" [autoGenerate]="true" (onColumnPinning)="columnPinning($event)"></igx-grid>
public columnPinning(event) {
    if (event.column.field === "Name") {
        event.insertAtIndex = 0;
    }
}

Custom Column Pinning UI

You can define your custom UI and change the pin state of the columns via the related API.

Let's say that instead of a toolbar you would like to define pin icons in the column headers that the end user can click to change the particular column's pin state. This can be done by creating a header template for the column with a custom icon.

<igx-grid #grid1 [data]="data" [width]="'100%'" [height]="'500px'">
    <igx-column #col *ngFor="let c of columns" [field]="c.field" [header]="c.header" [width]="c.width" [pinned]='c.pinned'
        [hidden]='c.hidden' [headerClasses]="'customHeaderSyle'">
        <ng-template igxHeader>
            <div class="title-inner">
                <span style="float:left">{{col.header}}</span>
                <igx-icon class="pin-icon" fontSet="fas" name="fa-thumbtack" (click)="toggleColumn(col)"></igx-icon>
            </div>
        </ng-template>
    </igx-column>
</igx-grid>

On click of the custom icon the pin state of the related column can be changed using the column's API methods.

public toggleColumn(col: IgxColumnComponent) {
    col.pinned ? col.unpin() : col.pin();
}

Demo


Pinning Limitations

  • Setting column widths in percentage (%) explicitly makes the Grid body and header content to be misaligned when there are pinned columns. For column pinning to function correctly the column widths should be in pixels (px) or auto-assigned by the Grid.

Troubleshooting

This section will provide you with hints what to do if you are having trouble with the Column Pinning feature.

Warnings

  • IgxGrid - The pinned area exceeds maximum pinned width. The following columns were unpinned to prevent further issues: ... . - This warning is thrown when the user has defined too many pinned columns initially. The combined width of the initially pinned columns should not exceed 80% of the Grid width. Otherwise the Grid by default takes the first columns (in order of their definition) that don't exceed the limit and the rest are unpinned (the columns listed in the warning). You can execute your own logic in order to determine if you want to unpin some columns manually on initialization using the onColumnInit event before the Grid initializes the pinning. It is triggered for each column.

API References

Additional Resources

Our community is active and always welcoming to new ideas.