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.
config = { theme: 'default' }How a theme works
Three layers. Each one fills only what the layer above it left unset.
- 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 · 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 · 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.
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.
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': 10becomes10px, and a duration becomesms. 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.
defaultThis 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
| Token | Paints | Default |
|---|---|---|
--gc-primaryAccent / Primary | Everywhere: sorted column, selection, focus, checkboxes, the active filter | #2563eb |
--gc-on-primaryText on accent | Text and icons on an accent fill: Apply, the AND/OR switch, count badges, the chosen day | #ffffff |
--gc-bgBackground | Everywhere without its own: the grid surface, and any part below not set on its own | #ffffff |
--gc-textText | Everywhere: cell, field and popup text | #0f172a |
--gc-text-mutedMuted text | Everywhere: hints, icons, placeholders, pagination text | #64748b |
--gc-border-colorBorder | Everywhere without its own: grid lines, header and row dividers | #e2e8f0 |
--gc-border-radiusCorner radius | Everywhere without its own: the frame, fields, popups and their buttons | 8px |
--gc-font-familyFont family | Everywhere | 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif |
--gc-font-sizeFont size | Every 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
| Token | Paints | Default |
|---|---|---|
--gc-grid-radiusFrame radius | The grid’s outer corners only | follows --gc-border-radius |
--gc-grid-shadowFrame shadow | The shadow round the grid’s frame | 0 1px 3px rgba(15, 23, 42, 0.04), 0 1px 2px rgba(15, 23, 42, 0.06) |
--gc-toolbar-bgToolbar background | The bar above the grid (export buttons) | follows --gc-header-bg |
--gc-footer-bgFooter background | The pagination bar under the grid | follows --gc-header-bg |
HeaderColumn header row, sort icons, resize handle & drag-over15
| Token | Paints | Default |
|---|---|---|
--gc-header-bgHeader background | The header row, its select-all checkbox and the scrollbar corner beside it | #f1f3f6 |
--gc-header-textHeader text | Header labels | #0f172a |
--gc-header-hover-bgHeader hover | A header cell under the pointer | #e5e8ec |
--gc-header-sorted-bgSorted column | The header cell of the sorted column | rgba(37, 99, 235, 0.06) |
--gc-header-font-sizeHeader font size | Header labels | 12.5px |
--gc-header-font-weightHeader weight | Header labels | 600 |
--gc-header-group-bgColumn group background | Header cells that group columns (“Inventory” over Price and Stock) | follows --gc-header-bg |
--gc-header-group-textColumn group text | The labels of column groups | follows --gc-header-text |
--gc-header-group-font-sizeColumn group text size | The text size of column-group labels | 13px |
--gc-sort-colorSort icon | Sort 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 text | The number inside a multi-sort rank badge | #ffffff |
--gc-drag-over-bgDrag-over | The header cell a dragged column will land on | rgba(37, 99, 235, 0.08) |
--gc-resize-handleResize handle | The column resize handle in the header | rgba(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
| Token | Paints | Default |
|---|---|---|
--gc-row-bgRow background | Odd 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 hover | The data row under the pointer | #f7f8fa |
--gc-row-selected-bgSelected row | Selected data rows | rgba(37, 99, 235, 0.08) |
--gc-row-landing-bgLanded row (after sort) | The row you were on, briefly, after a sort or filter moves it | rgba(37, 99, 235, 0.14) |
--gc-row-selected-hover-bgSelected + hover | A selected row under the pointer | rgba(37, 99, 235, 0.14) |
--gc-row-selected-pinned-bgSelected (pinned) | Pinned cells of a selected row | #eef3fd |
--gc-row-span-overlay-bgMerged cell background | Merged (row-spanning) cells | follows --gc-row-bg |
--gc-row-span-pending-edgeMerged cell pending edge | The edge of a merged cell still waiting for rows | follows --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 align | Number cells | end |
--gc-row-animation-durationReveal duration | Expanding detail panels | 200ms |
--gc-cell-focus-outlineFocus ring | The keyboard focus ring on cells, header and filter cells | follows --gc-primary |
--gc-cell-focus-outline-widthFocus ring width | The keyboard focus ring on cells, header and filter cells | 2px |
--gc-cell-focus-outline-offsetFocus ring offset | The keyboard focus ring on cells, header and filter cells | -2px |
PinnedSticky column shadows & edge3
| Token | Paints | Default |
|---|---|---|
--gc-pin-shadow-leftLeft-pin shadow | The shadow beside left-pinned columns | 0 0 0 0 transparent |
--gc-pin-shadow-rightRight-pin shadow | The shadow beside right-pinned columns | 0 0 0 0 transparent |
--gc-pin-edgePinned edge | The line between pinned and scrolling columns | follows --gc-border-color |
SummarySub-header & footer rows2
| Token | Paints | Default |
|---|---|---|
--gc-summary-top-bgSub-header bg | The summary row above the data | #eef3fd |
--gc-summary-bottom-bgFooter bg | The summary row below the data, and the scrollbar corner beside it | #f1f3f6 |
Filter rowThe row of filters under the header2
| Token | Paints | Default |
|---|---|---|
--gc-filter-row-bgFilter row background | The filter row’s cells (not the fields in them) | follows --gc-bg |
--gc-filter-focus-bgFocused filter cell | The filter-row cell whose field has focus | #ffffff |
FieldsEvery text field and dropdown trigger: filter row, pagination, filter popup6
| Token | Paints | Default |
|---|---|---|
--gc-input-bgField background | Every field: filter-row inputs and dropdowns, the page-size dropdown, the filter popup’s fields | follows --gc-bg |
--gc-input-borderField border | The border of every field | follows --gc-border-color |
--gc-input-radiusField radius | The corners of every field | follows --gc-border-radius |
--gc-input-focus-bgField focus background | A field while you type in it | follows --gc-bg |
--gc-input-focus-ringField focus ring | The glow round a field while you type in it or its list is open | rgba(37, 99, 235, 0.15) |
--gc-checkbox-radiusCheckbox radius | The corners of every checkbox: row selection, select-all, checkbox editors | 4px |
Popups & dropdownsThe filter popup, dropdown lists, the calendar and their options6
| Token | Paints | Default |
|---|---|---|
--gc-popup-bgPopup background | The filter popup, every dropdown list, the calendar, the chip popover | follows --gc-bg |
--gc-popup-borderPopup border | The border and dividers of every popup and dropdown list | follows --gc-border-color |
--gc-popup-radiusPopup radius | The corners of every popup and dropdown list | follows --gc-border-radius |
--gc-popup-shadowPopup shadow | The shadow under every popup and dropdown list | 0 8px 32px rgba(15, 23, 42, 0.12), 0 2px 8px rgba(15, 23, 42, 0.06) |
--gc-option-hover-bgOption hover | The option under the pointer or keyboard in a list, a calendar day | follows --gc-row-hover-bg |
--gc-option-selected-bgSelected option | The chosen option in a list, a checked filter-list row | rgba(37, 99, 235, 0.07) |
ButtonsToolbar, pagination and filter-popup buttons3
| Token | Paints | Default |
|---|---|---|
--gc-button-bgButton background | Toolbar buttons and the filter popup’s Clear and remove buttons | follows --gc-bg |
--gc-button-radiusButton radius | Toolbar, pagination and filter-popup buttons | 7px |
--gc-button-hover-bgButton hover | Any of the grid’s own buttons under the pointer | follows --gc-header-hover-bg |
StatesLoading skeleton & error colour3
| Token | Paints | Default |
|---|---|---|
--gc-skeleton-baseSkeleton base | Loading placeholders | #e5e8ec |
--gc-skeleton-highlightSkeleton highlight | The shimmer across loading placeholders | #f1f3f6 |
--gc-error-colorError | Error messages and invalid filter fields | #dc2626 |
TooltipThe tooltip over a cell or a header6
| Token | Paints | Default |
|---|---|---|
--gc-tooltip-bgTooltip background | The tooltip over a cell or a header | #0f172a |
--gc-tooltip-textTooltip text | The tooltip’s text | #f8fafc |
--gc-tooltip-borderTooltip border | The tooltip’s outline | transparent |
--gc-tooltip-radiusTooltip radius | The tooltip’s corners | 8px |
--gc-tooltip-shadowTooltip shadow | The shadow under the tooltip | 0 8px 24px -8px rgba(15, 23, 42, 0.45), 0 0 0 1px rgba(15, 23, 42, 0.06) |
--gc-tooltip-font-sizeTooltip text size | The tooltip’s text size | 12.5px |
EditingInvalid edits, their message, and the row being edited10
| Token | Paints | Default |
|---|---|---|
--gc-editor-invalid-borderInvalid edit border | The editor’s border while its value fails validation | #dc2626 |
--gc-editor-invalid-ringInvalid edit glow | The glow round an editor whose value fails validation | rgba(220, 38, 38, 0.15) |
--gc-editor-error-bgError message | The message under an invalid edit | #dc2626 |
--gc-editor-error-colorError message text | The text of that message | #ffffff |
--gc-editor-error-borderError message border | The border of that message | #b91c1c |
--gc-editor-error-font-sizeError message size | The text size of that message | 12px |
--gc-cell-invalid-bgInvalid cell | A cell whose value failed validation | rgba(220, 38, 38, 0.08) |
--gc-cell-invalid-outlineInvalid cell outline | The outline of a cell whose value failed validation | #dc2626 |
--gc-row-editing-bgRow being edited | The whole row while row editing is open | rgba(59, 130, 246, 0.06) |
--gc-row-editing-outlineRow being edited outline | The outline of the row being edited | rgba(59, 130, 246, 0.45) |
Cell typesChips, status badges, progress bars and image cells14
| Token | Paints | Default |
|---|---|---|
--gc-chip-bgChip background | Soft chips that have no colour of their own | #eef2ff |
--gc-chip-textChip text | Soft and outline chips that have no colour of their own | #3730a3 |
--gc-chip-borderChip border | Outline chips that have no colour of their own | #c7d2fe |
--gc-chip-solid-textSolid chip text | Text on solid chips | #ffffff |
--gc-chip-radiusChip corners | The corners of every chip | 999px |
--gc-chip-font-sizeChip text size | The text size of every chip | 12px |
--gc-badge-warningBadge warning | Status badges set to warning (success, error and info use the live-flash colours) | #d97706 |
--gc-badge-font-sizeBadge text size | The text size of every status badge | 12px |
--gc-progress-fillProgress fill | Progress bars that have no colour of their own | follows --gc-primary |
--gc-progress-trackProgress track | The empty part of every progress bar | #e2e8f0 |
--gc-img-radiusImage corners | The corners of rounded image cells | 6px |
--gc-img-shimmer-fromImage placeholder | An image cell while it loads | follows --gc-skeleton-base |
--gc-img-shimmer-toImage placeholder shine | The shine that sweeps a loading image cell | follows --gc-skeleton-highlight |
--gc-img-error-bgImage error | An image that failed to load | follows --gc-skeleton-base |
ScrollbarCustom scrollbar appearance6
| Token | Paints | Default |
|---|---|---|
--gc-scrollbar-widthScrollbar width | Both scrollbars | 8px |
--gc-scrollbar-thumbScrollbar thumb | The scrollbar thumbs (and thin lists inside popups) | #cbd5e1 |
--gc-scrollbar-trackScrollbar track | The vertical scrollbar track | transparent |
--gc-scrollbar-thumb-hoverScrollbar thumb (hover) | A scrollbar thumb under the pointer | #94a3b8 |
--gc-scrollbar-band-bgHorizontal band background | The horizontal scrollbar band | follows --gc-row-bg |
--gc-scrollbar-radiusScrollbar radius | The scrollbar thumbs | 4px |
Live FlashReal-time cell flash colours4
| Token | Paints | Default |
|---|---|---|
--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 neutral | A cell that just changed without rising or falling, and info badges | #2563eb |
--gc-flash-durationFlash duration | How long a changed cell stays highlighted | 700ms |