Home/Styling & Layout/Theming
Styling & Layout

Theming

Every colour, corner and font in the grid is a --gc-* CSS property. Pick one of five shipped themes, change a few properties, or build your own in the Theme Builder.

Built-in themes

Five themes ship with the grid. Switch them on one grid: every part follows, the dropdowns and the calendar included.

Sort, select, filter and open “Rows”.
First name
Last name
Department
Salary
Status
Alice
Anderson
Design
$86,000
Active
Bob
Anderson
Legal
$87,000
Inactive
Carol
Anderson
Product
$88,000
Active
David
Anderson
Support
$89,000
Active
Emma
Anderson
Engineering
$90,000
Active
Frank
Anderson
Marketing
$91,000
Active
Rows per page:
1–6 of 500
config = { theme: 'default' }
Make it yours in the Theme BuilderStart from Default, change the accent, the corners and every part on a live grid, then export SCSS, TypeScript or a link.Open in Theme Builder

How a theme works

Three layers. Each one fills only what the layer above it left unset.

  1. 1 · CoreNine values

    Accent, surface, text, muted text, border, text on accent, radius, font and font size. Every part follows them until it has its own.

    • --gc-primary
    • --gc-bg
    • --gc-text
    • --gc-border-color
  2. 2 · PartsA token per part

    The header, rows, fields, popups and buttons each have their own. Left unset, each one follows a Core value.

    • --gc-header-bg
    • --gc-popup-bgfollows --gc-bg
    • --gc-input-borderfollows --gc-border-color
  3. 3 · One grid[themeTokens]

    A few values on a single grid. They win over the theme class.

    • --gc-primaryon this grid only

Change --gc-primary once and it reaches the sort arrow, the selected row, the checkboxes, the focused field, the current page and the chosen option: every accent-coloured part of the preview above.

Apply a theme

Four ways in, from one grid to every grid in the app. The live examples follow.

config.themeA shipped theme, or your own class, on one grid.
// styles.scss, once
@use '@gridcraft/angular/themes/dark';

config = { theme: 'dark' };
.gc-theme-brandYour own theme, written once in global CSS.
.gc-theme-brand {
  --gc-primary:   #7c3aed;
  --gc-header-bg: #f5f3ff;
}
[themeTokens]A few values on one grid, with no CSS file.
tokens = {
  '--gc-primary': '#f59e0b',
  '--gc-border-radius': 10,
};
setTheme()Every grid at once, at runtime: a dark-mode switch or tenant branding.
inject(GridDirectionService)
  .setTheme(dark ? 'dark' : 'default');

Global CSS only. A theme class in a component's stylesheet never reaches the grid, and nothing warns you. Put it in styles.scss, or use [themeTokens]. For the same reason, never set tokens on your component's :host.

Your own theme class

A theme is a class holding --gc-* values. This grid runs theme: 'brand', eight properties in the app's global stylesheet: no fork, no !important, no component to extend.

First Name
Department
Status
Grace
Design
Active
Quinn
Design
Active
Alice
Design
Active
Kate
Design
Active
Uma
Design
Active
Emma
Design
Inactive
Olivia
Design
Active
Yara
Design
Active
Iris
Design
Active
Sam
Design
Active
Carol
Design
Active
Mia
Design
Active
12 / 500 records

Write the values you want to change under a .gc-theme-{name} class, then name it in config.theme. Everything you leave out keeps the default value, so a theme can be two lines or all of them.

It has to be global CSS

The class lands on the grid's own root element, inside the library's component. A rule in your component's stylesheet is rewritten with an [_ngcontent-…] attribute and never matches it: the grid draws the default theme and nothing tells you why. Put custom themes in styles.scss, or use [themeTokens], which needs no CSS at all.

[themeTokens] on one grid

The dark theme with four tokens changed on this grid only, through an input rather than a stylesheet. The base theme supplies everything else.

First Name
Department
Status
Grace
Design
Active
Quinn
Design
Active
Alice
Design
Active
Kate
Design
Active
Uma
Design
Active
Emma
Design
Inactive
Olivia
Design
Active
Yara
Design
Active
Iris
Design
Active
Sam
Design
Active
Carol
Design
Active
Mia
Design
Active
12 / 500 records
Applied over theme: 'dark':--gc-primary + --gc-header-text: #f59e0b · --gc-header-bg: #3f2d0b · --gc-border-radius: 10

Bind a GridThemeTokens object to change a few values on one grid, with no stylesheet. The grid writes them as inline properties on its root element, the same element that carries the gc-theme-* class, so they win over the class. The base theme still supplies everything you did not name.

  • Numbers get their unit. '--gc-border-radius': 10 becomes 10px, and a duration becomes ms. Strings pass through as written.
  • Per grid. Two grids on one page can carry different tokens over the same theme.
  • Live. Make the object a computed() and the grid follows it without being rebuilt. Change accent above does exactly that.

Follow the OS setting

This grid reads prefers-color-scheme. Change your operating system or browser appearance and it switches between default and dark without a reload.

First Name
Department
Status
Grace
Design
Active
Quinn
Design
Active
Alice
Design
Active
Kate
Design
Active
Uma
Design
Active
Emma
Design
Inactive
Olivia
Design
Active
Yara
Design
Active
Iris
Design
Active
Sam
Design
Active
Carol
Design
Active
Mia
Design
Active
12 / 500 records
prefers-color-scheme resolved to:default

This grid has no switch. It reads the reader's own setting and follows it, including a change made while the page is open:

const mq = window.matchMedia('(prefers-color-scheme: dark)');
this.dark.set(mq.matches);
mq.addEventListener('change', e => this.dark.set(e.matches));

Guard the read: this runs on the server too, where window does not exist. To switch every grid in the app at once instead, call GridDirectionService.setTheme(); a grid with its own config.theme keeps it.

Token reference

Every token, grouped by the part of the grid it paints: the same groups as the Theme Builder. “Follows” means an unset token takes that token's value.

CoreThe global values every part without its own follows9
TokenPaintsDefault
--gc-primaryAccent / PrimaryEverywhere: sorted column, selection, focus, checkboxes, the active filter#2563eb
--gc-on-primaryText on accentText and icons on an accent fill: Apply, the AND/OR switch, count badges, the chosen day#ffffff
--gc-bgBackgroundEverywhere without its own: the grid surface, and any part below not set on its own#ffffff
--gc-textTextEverywhere: cell, field and popup text#0f172a
--gc-text-mutedMuted textEverywhere: hints, icons, placeholders, pagination text#64748b
--gc-border-colorBorderEverywhere without its own: grid lines, header and row dividers#e2e8f0
--gc-border-radiusCorner radiusEverywhere without its own: the frame, fields, popups and their buttons8px
--gc-font-familyFont familyEverywhere'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
--gc-font-sizeFont sizeEvery text in the grid: cells, fields, toolbar, pagination, dropdowns, popups, the calendar (the header has its own)14px
Grid frame, toolbar & footerThe grid’s outer corners, the bar above it and the pagination bar below it4
TokenPaintsDefault
--gc-grid-radiusFrame radiusThe grid’s outer corners onlyfollows --gc-border-radius
--gc-grid-shadowFrame shadowThe shadow round the grid’s frame0 1px 3px rgba(15, 23, 42, 0.04), 0 1px 2px rgba(15, 23, 42, 0.06)
--gc-toolbar-bgToolbar backgroundThe bar above the grid (export buttons)follows --gc-header-bg
--gc-footer-bgFooter backgroundThe pagination bar under the gridfollows --gc-header-bg
HeaderColumn header row, sort icons, resize handle & drag-over15
TokenPaintsDefault
--gc-header-bgHeader backgroundThe header row, its select-all checkbox and the scrollbar corner beside it#f1f3f6
--gc-header-textHeader textHeader labels#0f172a
--gc-header-hover-bgHeader hoverA header cell under the pointer#e5e8ec
--gc-header-sorted-bgSorted columnThe header cell of the sorted columnrgba(37, 99, 235, 0.06)
--gc-header-font-sizeHeader font sizeHeader labels12.5px
--gc-header-font-weightHeader weightHeader labels600
--gc-header-group-bgColumn group backgroundHeader cells that group columns (“Inventory” over Price and Stock)follows --gc-header-bg
--gc-header-group-textColumn group textThe labels of column groupsfollows --gc-header-text
--gc-header-group-font-sizeColumn group text sizeThe text size of column-group labels13px
--gc-sort-colorSort iconSort arrows in the header#94a3b8
--gc-sort-active-colorSort icon (active)The sorted column’s arrow and rank badge#2563eb
--gc-sort-badge-textSort rank textThe number inside a multi-sort rank badge#ffffff
--gc-drag-over-bgDrag-overThe header cell a dragged column will land onrgba(37, 99, 235, 0.08)
--gc-resize-handleResize handleThe column resize handle in the headerrgba(15, 23, 42, 0.20)
--gc-resize-handle-hoverResize (hover)The column resize handle under the pointer#2563eb
RowsData rows, zebra, hover, selection & the focus ring15
TokenPaintsDefault
--gc-row-bgRow backgroundOdd data rows (and the horizontal scrollbar band if it has no colour)#ffffff
--gc-row-even-bgEven row (zebra)Even data rows (zebra)#ffffff
--gc-row-hover-bgRow hoverThe data row under the pointer#f7f8fa
--gc-row-selected-bgSelected rowSelected data rowsrgba(37, 99, 235, 0.08)
--gc-row-landing-bgLanded row (after sort)The row you were on, briefly, after a sort or filter moves itrgba(37, 99, 235, 0.14)
--gc-row-selected-hover-bgSelected + hoverA selected row under the pointerrgba(37, 99, 235, 0.14)
--gc-row-selected-pinned-bgSelected (pinned)Pinned cells of a selected row#eef3fd
--gc-row-span-overlay-bgMerged cell backgroundMerged (row-spanning) cellsfollows --gc-row-bg
--gc-row-span-pending-edgeMerged cell pending edgeThe edge of a merged cell still waiting for rowsfollows --gc-border-color
--gc-row-selected-hover-pinned-bgSel.+hover (pinned)Pinned cells of a selected row under the pointer#e0e9fc
--gc-cell-numeric-alignNumeric cell alignNumber cellsend
--gc-row-animation-durationReveal durationExpanding detail panels200ms
--gc-cell-focus-outlineFocus ringThe keyboard focus ring on cells, header and filter cellsfollows --gc-primary
--gc-cell-focus-outline-widthFocus ring widthThe keyboard focus ring on cells, header and filter cells2px
--gc-cell-focus-outline-offsetFocus ring offsetThe keyboard focus ring on cells, header and filter cells-2px
PinnedSticky column shadows & edge3
TokenPaintsDefault
--gc-pin-shadow-leftLeft-pin shadowThe shadow beside left-pinned columns0 0 0 0 transparent
--gc-pin-shadow-rightRight-pin shadowThe shadow beside right-pinned columns0 0 0 0 transparent
--gc-pin-edgePinned edgeThe line between pinned and scrolling columnsfollows --gc-border-color
SummarySub-header & footer rows2
TokenPaintsDefault
--gc-summary-top-bgSub-header bgThe summary row above the data#eef3fd
--gc-summary-bottom-bgFooter bgThe summary row below the data, and the scrollbar corner beside it#f1f3f6
Filter rowThe row of filters under the header2
TokenPaintsDefault
--gc-filter-row-bgFilter row backgroundThe filter row’s cells (not the fields in them)follows --gc-bg
--gc-filter-focus-bgFocused filter cellThe filter-row cell whose field has focus#ffffff
FieldsEvery text field and dropdown trigger: filter row, pagination, filter popup6
TokenPaintsDefault
--gc-input-bgField backgroundEvery field: filter-row inputs and dropdowns, the page-size dropdown, the filter popup’s fieldsfollows --gc-bg
--gc-input-borderField borderThe border of every fieldfollows --gc-border-color
--gc-input-radiusField radiusThe corners of every fieldfollows --gc-border-radius
--gc-input-focus-bgField focus backgroundA field while you type in itfollows --gc-bg
--gc-input-focus-ringField focus ringThe glow round a field while you type in it or its list is openrgba(37, 99, 235, 0.15)
--gc-checkbox-radiusCheckbox radiusThe corners of every checkbox: row selection, select-all, checkbox editors4px
Popups & dropdownsThe filter popup, dropdown lists, the calendar and their options6
TokenPaintsDefault
--gc-popup-bgPopup backgroundThe filter popup, every dropdown list, the calendar, the chip popoverfollows --gc-bg
--gc-popup-borderPopup borderThe border and dividers of every popup and dropdown listfollows --gc-border-color
--gc-popup-radiusPopup radiusThe corners of every popup and dropdown listfollows --gc-border-radius
--gc-popup-shadowPopup shadowThe shadow under every popup and dropdown list0 8px 32px rgba(15, 23, 42, 0.12), 0 2px 8px rgba(15, 23, 42, 0.06)
--gc-option-hover-bgOption hoverThe option under the pointer or keyboard in a list, a calendar dayfollows --gc-row-hover-bg
--gc-option-selected-bgSelected optionThe chosen option in a list, a checked filter-list rowrgba(37, 99, 235, 0.07)
ButtonsToolbar, pagination and filter-popup buttons3
TokenPaintsDefault
--gc-button-bgButton backgroundToolbar buttons and the filter popup’s Clear and remove buttonsfollows --gc-bg
--gc-button-radiusButton radiusToolbar, pagination and filter-popup buttons7px
--gc-button-hover-bgButton hoverAny of the grid’s own buttons under the pointerfollows --gc-header-hover-bg
StatesLoading skeleton & error colour3
TokenPaintsDefault
--gc-skeleton-baseSkeleton baseLoading placeholders#e5e8ec
--gc-skeleton-highlightSkeleton highlightThe shimmer across loading placeholders#f1f3f6
--gc-error-colorErrorError messages and invalid filter fields#dc2626
TooltipThe tooltip over a cell or a header6
TokenPaintsDefault
--gc-tooltip-bgTooltip backgroundThe tooltip over a cell or a header#0f172a
--gc-tooltip-textTooltip textThe tooltip’s text#f8fafc
--gc-tooltip-borderTooltip borderThe tooltip’s outlinetransparent
--gc-tooltip-radiusTooltip radiusThe tooltip’s corners8px
--gc-tooltip-shadowTooltip shadowThe shadow under the tooltip0 8px 24px -8px rgba(15, 23, 42, 0.45), 0 0 0 1px rgba(15, 23, 42, 0.06)
--gc-tooltip-font-sizeTooltip text sizeThe tooltip’s text size12.5px
EditingInvalid edits, their message, and the row being edited10
TokenPaintsDefault
--gc-editor-invalid-borderInvalid edit borderThe editor’s border while its value fails validation#dc2626
--gc-editor-invalid-ringInvalid edit glowThe glow round an editor whose value fails validationrgba(220, 38, 38, 0.15)
--gc-editor-error-bgError messageThe message under an invalid edit#dc2626
--gc-editor-error-colorError message textThe text of that message#ffffff
--gc-editor-error-borderError message borderThe border of that message#b91c1c
--gc-editor-error-font-sizeError message sizeThe text size of that message12px
--gc-cell-invalid-bgInvalid cellA cell whose value failed validationrgba(220, 38, 38, 0.08)
--gc-cell-invalid-outlineInvalid cell outlineThe outline of a cell whose value failed validation#dc2626
--gc-row-editing-bgRow being editedThe whole row while row editing is openrgba(59, 130, 246, 0.06)
--gc-row-editing-outlineRow being edited outlineThe outline of the row being editedrgba(59, 130, 246, 0.45)
Cell typesChips, status badges, progress bars and image cells14
TokenPaintsDefault
--gc-chip-bgChip backgroundSoft chips that have no colour of their own#eef2ff
--gc-chip-textChip textSoft and outline chips that have no colour of their own#3730a3
--gc-chip-borderChip borderOutline chips that have no colour of their own#c7d2fe
--gc-chip-solid-textSolid chip textText on solid chips#ffffff
--gc-chip-radiusChip cornersThe corners of every chip999px
--gc-chip-font-sizeChip text sizeThe text size of every chip12px
--gc-badge-warningBadge warningStatus badges set to warning (success, error and info use the live-flash colours)#d97706
--gc-badge-font-sizeBadge text sizeThe text size of every status badge12px
--gc-progress-fillProgress fillProgress bars that have no colour of their ownfollows --gc-primary
--gc-progress-trackProgress trackThe empty part of every progress bar#e2e8f0
--gc-img-radiusImage cornersThe corners of rounded image cells6px
--gc-img-shimmer-fromImage placeholderAn image cell while it loadsfollows --gc-skeleton-base
--gc-img-shimmer-toImage placeholder shineThe shine that sweeps a loading image cellfollows --gc-skeleton-highlight
--gc-img-error-bgImage errorAn image that failed to loadfollows --gc-skeleton-base
ScrollbarCustom scrollbar appearance6
TokenPaintsDefault
--gc-scrollbar-widthScrollbar widthBoth scrollbars8px
--gc-scrollbar-thumbScrollbar thumbThe scrollbar thumbs (and thin lists inside popups)#cbd5e1
--gc-scrollbar-trackScrollbar trackThe vertical scrollbar tracktransparent
--gc-scrollbar-thumb-hoverScrollbar thumb (hover)A scrollbar thumb under the pointer#94a3b8
--gc-scrollbar-band-bgHorizontal band backgroundThe horizontal scrollbar bandfollows --gc-row-bg
--gc-scrollbar-radiusScrollbar radiusThe scrollbar thumbs4px
Live FlashReal-time cell flash colours4
TokenPaintsDefault
--gc-flash-up-textFlash up (▲)A cell whose number just rose, and success badges#15803d
--gc-flash-down-textFlash down (▼)A cell whose number just fell, and error badges#b91c1c
--gc-flash-neutral-textFlash neutralA cell that just changed without rising or falling, and info badges#2563eb
--gc-flash-durationFlash durationHow long a changed cell stays highlighted700ms