Blazor Hierarchical Grid Row Pinning

    The Ignite UI for Blazor Row Pinning feature in Blazor Hierarchical Grid allows you to pin one or multiple rows to the top or bottom of grid. Row Pinning allows end-users to pin rows in a particular order, duplicating them in a special area that is always visible even when they scroll the IgbHierarchicalGrid vertically. The Blazor Hierarchical Grid has a built-in row pinning UI, which is enabled by initializing an IgbActionStrip component in the context of Hierarchical Grid. In addition, you can define custom UI and change the pin state of the rows via the Row Pinning API.

    Blazor Hierarchical Grid Row Pinning Example

    EXAMPLE
    MODULES
    DATA
    RAZOR
    JS
    CSS

    Like this sample? Get access to our complete Ignite UI for Blazor toolkit and start building your own apps in minutes. Download it for free.

    Row Pinning UI

    The built-in row pinning UI is enabled by adding an IgbActionStrip component with the IgbGridPinningActions component. The action strip is automatically shown when hovering a row and will display a pin or unpin button icon based on the state of the row it is shown for. An additional action allowing to scroll the copy of the pinned row into view is shown for each pinned row as well.

        <IgbHierarchicalGrid Width="100%"  
                 Height="100%"
                 PrimaryKey="Key"
                 AutoGenerate=true
                 Data=northwindEmployees
                 RowEditable=true>
            <IgbColumn Field="ID" Editable=false></IgbColumn>
            <IgbColumn Field="ContactName"></IgbColumn>
            <IgbColumn Field="ContactTitle"></IgbColumn>
            <IgbColumn Field="City" Sortable=true></IgbColumn>
            <IgbColumn Field="CompanyName" Sortable=true></IgbColumn>
            <IgbColumn Field="Fax" Sortable=true></IgbColumn>
            <IgbColumn Field="Address" Sortable=true></IgbColumn>
            <IgbColumn Field="PostalCode" Sortable=true></IgbColumn>
            <IgbColumn Field="Country" Sortable=true></IgbColumn>
            <IgbColumn Field="Phone" Sortable=true></IgbColumn>
            <IgbActionStrip>
                <IgbGridPinningActions></IgbGridPinningActions>
                <IgbGridEditingActions></IgbGridEditingActions>
            </IgbActionStrip>
        </IgbHierarchicalGrid>
    razor

    Row Pinning API

    Row pinning is controlled through the Pinned input of the Row. Pinned rows are rendered at the top of the IgbHierarchicalGrid by default and stay fixed through vertical scrolling of the unpinned rows in the IgbHierarchicalGrid body.

    this.Grid.PinRowAsync("ALFKI", 0);
    razor

    You may also use the IgbHierarchicalGrid's PinRow or UnpinRow methods of the to pin or unpin records by their ID:

    this.Grid.PinRowAsync("ALFKI", 0);
    this.Grid.UnpinRowAsync("ALFKI");
    razor

    Note that the row ID is the primary key value, defined by the PrimaryKey of the grid, or the record instance itself. Both methods return a boolean value indicating whether their respective operation is successful or not. Usually the reason they fail is that the row is already in the desired state.

    A row is pinned below the last pinned row. Changing the order of the pinned rows can be done by subscribing to the RowPinning event and changing the InsertAtIndex property of the event arguments to the desired position index.

    <IgbHierarchicalGrid Width="100%"
                 Id="grid"
                 RowPinningScript="rowPinningHandler"
                 Height="100%"
                 PrimaryKey="Key"
                 AutoGenerate="true"
                 Data="northwindEmployees">
    </IgbHierarchicalGrid>
    razor
    *** In JavaScript ***
    
    function rowPinningHandler(event) {
        event.detail.insertAtIndex = 0;
    }
    
    igRegisterScript("rowPinningHandler", rowPinningHandler, false);
    razor

    Pinning Position

    You can change the row pinning position via the Pinning configuration option. It allows you to set the pin area position to either Top or Bottom. When set to Bottom pinned rows are rendered at the bottom of the grid, after the unpinned rows. Unpinned rows can be scrolled vertically, while the pinned rows remain fixed at the bottom.

        <IgbHierarchicalGrid Id="grid"
                Width="100%"
                Height="100%"
                Pinning=PinningConfig
                PrimaryKey="Key"
                AutoGenerate=true
                Data=northwindEmployees>
        </IgbHierarchicalGrid>
        @code {
            public string Key = "ID";
            private Northwind.EmployeesType[] northwindEmployees = Array.Empty<Northwind.EmployeesType>();
            public IgbPinningConfig PinningConfig = new IgbPinningConfig()
            {
                Rows = RowPinningPosition.Bottom
            };
            protected override async Task OnInitializedAsync()
            {
                northwindEmployees = await this.northwindService.GetEmployees() ?? northwindEmployees;
            }
        }
    razor

    Custom Row Pinning UI

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

    Via extra column with icon

    Let's say that instead of an action strip you would like to show a pin icon in every row allowing the end-user to click and change a particular row's pin state. This can be done by adding an extra column with a cell template containing the custom icon.

    <IgbColumn Width="70px" BodyTemplateScript="WebHierarchicalGridRowPinCellTemplate"/>
    
    // In Javascript
    
    igRegisterScript("WebHierarchicalGridRowPinCellTemplate", (ctx) => {
        var html = window.igTemplating.html;
        window.toggleRowPin = function toggleRowPin(row) {
            row.pinned = !row.pinned;
        }
    	const row = ctx.cell.row;
        return html`<div>
        <span onpointerdown='toggleRowPin("${row}")'>📌</span>
    </div>`;
    }, false);
    razor

    Demo

    EXAMPLE
    MODULES
    DATA
    RAZOR
    JS
    CSS

    Row Pinning Limitations

    • Only records that exist in the data source can be pinned.
    • The row pinning state is not exported to excel. The grid is exported as if no row pinning is applied.
    • The copies of pinned rows in the scrollable area of the grid are an integral part of how other grid features achieve their functionality in the presence of pinned rows and therefore their creation cannot be disabled nor can they be removed.
    • As Row Selection works entirely with row Ids, selecting pinned rows selects their copies as well (and vice versa). Additionally, range selection (e.g. using Shift + click) within the pinned area works the same way as selecting a range of rows within the scrollable area. The resulting selection includes all rows in between even if they are not currently pinned. Getting the selected rows through the API only returns a single instance of each selected record.

    Styling

    In addition to the predefined themes, the grid could be further customized by setting some of the available CSS properties. In case you would like to change some of the colors, you need to set a class for the grid first:

    <IgbHierarchicalGrid class="grid"></IgbHierarchicalGrid>
    razor

    Then set the related CSS properties for that class:

    .grid {
        --ig-grid-pinned-border-width: 5px;
        --ig-grid-pinned-border-style: double;
        --ig-grid-pinned-border-color: #FFCD0F;
        --ig-grid-cell-active-border-color: #FFCD0F;
    }
    css

    Demo

    EXAMPLE
    MODULES
    DATA
    RAZOR
    JS
    CSS

    API References

    Additional Resources

    Our community is active and always welcoming to new ideas.