React Pivot Grid Theming

A Pivot Grid theme can be built from just a background, foreground and accent color, with every other color derived from them - the header, the rows, the borders, the summaries, the toolbar, the paginator and the filtering popups. The derived colors don’t need to be written by hand; generate them with grid-theme(), the Theming MCP or the theme playground.

The derivation lives in the generated theme, not in the component. Out of the box, each --ig-grid-* property is independent and changes only its own part of the Pivot Grid - see Fine-tune individual properties.

React Pivot Grid Theming Example

The four themes below are custom - written for this sample, not shipped with the library. They share one generated block of derived tokens, so each theme only sets the primary tokens plus a few surface and border colors. Switching between them shows how far those few values reach in a generated theme.

Create a theme

A generated theme is a block of --ig-grid-* custom properties declared on a class. The block holds the three primary tokens, plus every other token written as a CSS expression over them:

.my-grid {
  --ig-grid-background: #08002e;
  --ig-grid-accent-color: #ff7d52;
  --ig-grid-foreground: hsla(from color(from var(--ig-grid-background) var(--y-contrast)) h 0 l/1);
  --ig-grid-header-background: color-mix(in srgb, var(--ig-grid-foreground) 6%, var(--ig-grid-background));
  --ig-grid-header-text-color: var(--ig-grid-foreground);
  --ig-grid-row-hover-background: color-mix(in srgb, var(--ig-grid-accent-color) 8%, var(--ig-grid-row-odd-background));
  /* … and the rest of the token set */
}

Pick the route that fits your toolchain - each one produces this same token set.

Sass

If your project compiles Sass, the theming engine can write the token set for you by using the grid-theme() function. To use it, first install the theming package:

npm install igniteui-theming

Then import the package, which exports the theme functions and the tokens() mixin:

@use "igniteui-theming" as *;

Then declare the theme with grid-theme and include it on the element you want to affect:

.my-grid {
  @include tokens(grid-theme(
    $background: #08002e,
    $accent-color: #ff7d52
  ));
}

Each parameter maps to the token of the same name - $background to --ig-grid-background, $accent-color to --ig-grid-accent-color - and every token you leave out is emitted as an expression over the ones you set.

Theming MCP

The Ignite UI Theming MCP generates the theme through your AI assistant. Ask for CSS output and it returns ready-to-use custom properties, so no local Sass toolchain is needed.

“Create a CSS grid theme for the .my-grid class with background #08002e and accent color #ff7d52.”

Theme playground

The theme playground at the end of this topic generates the token set for any colors you pick. Select Show code to copy the complete CSS block.

Keep the theme up to date

A generated CSS block is a snapshot of the library version it was generated for. Regenerate it after a Ignite UI for React upgrade to pick up any new changes to the grid theme. With grid-theme(), upgrade igniteui-theming together with your other Ignite UI for React packages and rebuild - it is a separate package, so upgrading the components alone does not update it. With the Theming MCP or the playground, run the same prompt or colors again and replace the block.

Apply the theme

Apply the class to the Pivot Grid:

The Pivot Grid manages its own class attribute, so put the theme class on a container element instead. The tokens are inherited by the Pivot Grid inside it:

<div className="my-grid">
    <IgrPivotGrid></IgrPivotGrid>
</div>

With the class applied, the theme is complete. The Pivot Grid is now dark indigo with a coral accent, and the text, header, row borders, hover states, selection tints and popup chrome have all been computed from those two values. From here on, the primary tokens are all you need to change.

Primary tokens

In a generated theme, the Pivot Grid is built from three primary tokens and every other color follows them.

--ig-grid-foreground is listed as primary but rarely needs setting. Left alone, it is chosen for contrast against the background, so a dark background produces light text and a light one produces dark text without a second declaration.

How derivation works

The derived tokens in a generated theme are not fixed colors. Each one is a CSS expression over the primary tokens:

.my-grid {
  --ig-grid-foreground: hsla(from color(from var(--ig-grid-background) var(--y-contrast)) h 0 l/1);
  --ig-grid-header-background: color-mix(in srgb, var(--ig-grid-foreground) 6%, var(--ig-grid-background));
  --ig-grid-row-hover-background: color-mix(in srgb, var(--ig-grid-accent-color) 8%, var(--ig-grid-row-odd-background));
  --ig-grid-sorted-header-icon-color: hsl(from var(--ig-grid-accent-color) h s l/0.7);
}

Two consequences follow. First, changing a primary token re-computes everything downstream, including at runtime through CSS custom properties. Second, the relationships hold whatever value you supply, so a theme cannot fall out of step with itself. Both hold only while the generated tokens are declared - remove them and every property goes back to being independent.

Going deeper

In a generated theme, some tokens are derivation roots in their own right. Declaring one detaches it from the background, and whatever sits on it should derive from the new value instead.

--ig-grid-header-background is the clearest example. Left alone it is mixed from --ig-grid-background, and the header text follows --ig-grid-foreground. Declare it, and the header text is re-derived to take contrast against the header background itself:

.my-grid {
  --ig-grid-header-background: #ff7d52;
  --ig-grid-header-text-color: hsla(from color(from var(--ig-grid-header-background) var(--y-contrast)) h 0 l/1);
}

Structure

Color is only half of a theme. Density and roundness are controlled by global design-system tokens rather than grid tokens, so you set them alongside the grid tokens:

.my-grid {
  --ig-size: var(--ig-size-small);   /* small | medium | large */
  --ig-radius-factor: 0;             /* 0 to 1 */
}

Grid lines are theme tokens too. To hide one, tint it to the surface behind it rather than removing it, so the row metrics do not change between themes:

.my-grid {
  /* horizontal dividers, blended away */
  --ig-grid-row-border-color: var(--ig-grid-background);
  /* vertical dividers, drawn in the same color the theme derives for rows */
  --ig-grid-body-column-border-color-odd: hsl(from color-mix(in srgb, var(--ig-grid-foreground) 16%, var(--ig-grid-background)) h s l/0.38);
  --ig-grid-body-column-border-color-even: hsl(from color-mix(in srgb, var(--ig-grid-foreground) 16%, var(--ig-grid-background)) h s l/0.38);
}

Fine-tune individual properties

Out of the box, every --ig-grid-* property is independent. Each one resolves against the base palette - in the Material theme, for example, the header reads var(--ig-grid-header-background, var(--ig-gray-100)) - so a single override changes only that part of the Pivot Grid and leaves the rest of the design untouched. This makes targeted adjustments safe and predictable:

.my-grid {
  --ig-grid-header-background: #120b3d;
  --ig-grid-header-text-color: #ffffff;
}

The same independence applies to the primary tokens. Without a generated theme, --ig-grid-background and --ig-grid-accent-color are ordinary properties and do not carry into the rest of the Pivot Grid:

/* The background changes, the header stays gray. */
.my-grid {
  --ig-grid-background: #08002e;
  --ig-grid-accent-color: #ff7d52;
}

To restyle the whole Pivot Grid from a few colors, create a theme.

Try it

Change a color and watch it reach the header, the rows, the summaries, the paginator and the filtering popups. Switch grids to confirm the same tokens serve all of them, then select Show code to copy the complete CSS block - the primary tokens together with every derived token.

API References

Additional Resources

• Pivot Grid Overview

• Palettes

• Typography

Our community is active and always welcoming to new ideas.

• Ignite UI for React Forums
• Ignite UI for React GitHub