Using the Ignite UI for Web Components grids

Required Workflow

1. Pick the grid type/package using the table below; ask if ambiguous.
2. Use only the verified import paths in this file (igniteui-webcomponents-grids, grids/combined.js, themes/<variant>/<design>.css). For anything else (toolbar, export, pivot/tree/hierarchical APIs, properties/events), look it up with list_components({ framework: "webcomponents", ... }) / get_doc({ framework: "webcomponents", name: "<doc-name>" }) / search_api({ platform: "webcomponents", query: "<keyword>" }) / get_api_reference({ platform: "webcomponents", component: "<ClassName>" }) instead of guessing.

Choosing the Grid

Never mix igc-grid-lite with a premium grid type for the same table — pick one. For upgrading Grid Lite to igc-grid, use the migration skill above.

For Grid Lite, import the igniteui-grid-lite package and its elements directly. Load only the base Ignite UI theme; do not import the premium grid package or grid theme:

import { IgcGridLite, IgcGridLiteColumn } from 'igniteui-grid-lite';
import 'igniteui-webcomponents/themes/light/material.css';

Theming Setup

• Pick exactly one design system (material | bootstrap | fluent | indigo) and one variant (light | dark) for the whole app. Never load two design systems together, and never load both a light and a dark file at once — toggle between the matching light/dark pair of the same design system instead.

• For premium grids only (igc-grid, igc-tree-grid, igc-hierarchical-grid, igc-pivot-grid), load both the base theme and the grid theme, same design system + variant — the grid package ships its own theme file for its internal structure (headers, cells, sort/filter icons, resize handles):

  import 'igniteui-webcomponents/themes/light/material.css';
  import 'igniteui-webcomponents-grids/grids/themes/light/material.css';
  

  Path pattern for both packages: themes/<light|dark>/<material|bootstrap|fluent|indigo>.css (grid package: igniteui-webcomponents-grids/grids/themes/...).

• These are document-level imports — they style the light DOM only. If the grid renders inside a Shadow root, see Shadow DOM below; a bare import never crosses into a shadow root.

Registering Components

For premium grids, register only the selected grid type:

import { IgcGridComponent } from 'igniteui-webcomponents-grids';
IgcGridComponent.register();

// Base package — register only what you use, not defineAllComponents()
import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents';
defineComponents(IgcButtonComponent);

Use the corresponding Igc*GridComponent.register() method for tree, hierarchical, or pivot grids. Use igniteui-webcomponents-grids/grids/combined.js only when the application intentionally uses all premium grid types.

Built-in grid glyphs (sort direction, filter, expand/collapse) come from the library's internal SVG icon collection and render automatically once the grid module above is registered — no icon font and no manual registerIcon/registerIconFromText call is needed for them. Only register icons for custom glyphs the app adds itself.

Shadow DOM

The most common cause of a "broken grid" (e.g. a checkbox expanding to 1000px+ wide) is a Lit component rendering <igc-grid> in its own shadow tree without the grid theme reaching that tree. Import the theme as an inline string and inject it as a <style> tag in render():

import { html, LitElement } from 'lit';
import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';

class MyGridPanel extends LitElement {
  private readonly data: Array<{ name: string }> = [
    { name: 'Ada Lovelace' },
  ];

  render() {
    return html`
      <style>${gridTheme}</style>
      <igc-grid .data=${this.data} allow-filtering="true" height="100%">
        <igc-column field="name" sortable="true" filterable="true"></igc-column>
      </igc-grid>
    `;
  }
}

The ?inline suffix is Vite-specific. In other bundlers, use their equivalent method for raw-string CSS imports. If the grid looks broken, fix the missing theme injection — do not mask the symptom with fallback CSS overrides.

Fluid Layout

Let the grid fill its container instead of hardcoding pixel heights:

.app-shell { display: flex; flex-direction: column; block-size: 100vh; }
.app-header { flex: 0 0 auto; }                 /* fixed-height header */
.app-content { display: flex; flex-direction: column; flex: 1 1 auto; min-height: 0; }  /* min-height: 0 lets this row shrink instead of overflow */
igc-grid { flex: 1 1 auto; min-height: 0; block-size: 100%; }

• The grid still needs a resolvable height for row virtualization — get it from the fluid layout (100% of a sized ancestor), not a guessed fixed pixel value on the grid itself.
• Omit column width unless a column needs a fixed size — columns are fluid by default; leave at least one column without width to absorb remaining space.

Sorting & Filtering

<igc-grid allow-filtering="true" height="100%">
  <igc-column field="name" sortable="true" filterable="true"></igc-column>
</igc-grid>

allow-filtering="true" on the grid is required for the filtering UI to appear — a column's filterable="true" alone has no visible effect. Boolean-looking attributes take quoted string values (sortable="true", not bare sortable). For events, remote sort/filter, or programmatic APIs, see the migration skill above (same API whether or not the app is migrating from Grid Lite).

Verify with a Clean Run

• No console errors/warnings (missing element definitions, CSS import errors)
• Grid fully styled per the chosen design system — no unstyled/browser-default look
• Sort/filter icons render as glyphs, not empty boxes or ligature text
• Filtering UI is visible; sorting and filtering both work interactively
• Grid keeps filling its container on resize — no trailing empty space, no clipped rows
• No leftover commented-out theme blocks from an earlier attempt

Key Rules

1. One design system, one variant, everywhere — never mix design systems or light/dark files.
2. Always load both the base theme and the grid theme for that same design system + variant.
3. Inject the grid theme into every Shadow root that renders <igc-grid>/<igc-tree-grid>/<igc-hierarchical-grid>/<igc-pivot-grid>.
4. Register only the selected grid type and components actually used — no defineAllComponents(), no "just in case" bundles.
5. Never guess deep import paths or APIs beyond what's verified here — look them up.
6. Fluid layout by default: min-height: 0 + flex/grid sizing; fixed pixel heights only when explicitly required.
7. allow-filtering="true" on the grid + sortable/filterable per column to enable sorting/filtering UI.
8. Fix root causes (missing theme/registration) instead of papering over symptoms with fallback CSS.