Skip to content

gotchas.md

Latest commit

 

History

History
189 lines (153 loc) · 7.57 KB

gotchas.md

File metadata and controls

189 lines (153 loc) · 7.57 KB

Ignite UI Angular Gotchas & Pitfalls

Table of Contents

Sass Conflicts

contrast() function collision

The CSS contrast() filter function can collide with igniteui-theming's contrast() Sass function. When you need the native CSS function, call it explicitly via sass:meta:

@use "sass:meta";

.uses-css-contrast {
  filter: meta.call(meta.get-function("contrast", $css: true), <contrast-value>);
}

Prefer this approach over string escaping when a native CSS function name collides with a Sass function.

Font family in typography mixin

Comma-separated font families are parsed as multiple Sass arguments. Wrap in parentheses:

// BAD
@include typography($font-family: "Primary Font", "Fallback Font", sans-serif);

// GOOD
@include typography($font-family: ("Primary Font", "Fallback Font", sans-serif));

Replace "Primary Font" and "Fallback Font" with the font families extracted from the design image.

Chart Properties

Markers shown by default

Category charts show markers at every data point by default. If the screenshot does not show markers, set markerTypes to the matching no-marker option documented for the component:

[markerTypes]="<resolvedMarkerTypes>"

markerTypes expects values such as "Circle" or "None", or an IgxMarkerTypeCollection. Do not pass an array of lowercase strings.

plotAreaBackground does NOT exist on igx-category-chart

Use CSS to style the chart container background instead.

areaFillOpacity exists on IgxCategoryChartComponent (via domain chart parent)

It does NOT exist on IgxSparklineComponent.

includedProperties must be a bound array

Use property binding, not a plain string attribute:

<igx-category-chart [includedProperties]="['fieldOne', 'fieldTwo', 'fieldThree']"></igx-category-chart>

Replace 'fieldOne', 'fieldTwo', etc. with the actual data property names from your mock data.

Chart callback inputs must use Angular property binding

Function-valued chart inputs must be bound, not passed as plain attributes:

<igx-category-chart [xAxisFormatLabel]="<labelFormatter>"></igx-category-chart>

Smooth area charts

For smooth-looking area charts where the data should appear continuous rather than spiky:

  • Increase data density until the line or area reads as continuous at the rendered size
  • Apply smoothing only when the source shape in the design looks smoothed rather than point-to-point
  • Hide markers unless the screenshot clearly shows visible data points
  • Tune fill opacity and label density to match the screenshot instead of relying on a fixed default

Charts inside CSS Grid can collapse

In a flexible CSS Grid track, set min-height: 0 on the grid cell and height: 100% on the chart element:

.chart-panel {
  min-height: 0;
}

igx-category-chart {
  display: block;
  height: 100%;
}

Component Properties

roundShape does NOT exist on IgxAvatarComponent

Use the supported shape input alone. Do not add [roundShape]="true".

IgxListLineDirective is the directive for igxListLine

It must be imported for list item text content. Confirm the exact package variant and entry point from the workspace and component docs before adding the import.

Avatar background color via CSS variable

<igx-avatar [style.--ig-avatar-background]="color"></igx-avatar>

Theming Pitfalls

DV components do NOT inherit Sass theme colors

Charts, maps, gauges, and sparklines ignore the global Sass theme. Set their visual properties explicitly via component inputs. After a palette exists, prefer palette tokens or local semantic CSS variables over leaving raw color literals in the final template:

[brushes]="'<resolved-series-brush>'"
[outlines]="'<resolved-series-outline>'"
[xAxisLabelTextColor]="'<resolved-axis-label-color>'"
[yAxisMajorStroke]="'<resolved-grid-line-color>'"

Component theme functions

For core UI component theming, prefer create_component_theme and apply the returned theme block as generated by the MCP server.

Nav drawer width

Override the drawer aside width via its internal class using the width measured from the design image:

igx-nav-drawer {
  --ig-nav-drawer-size: <extracted-sidebar-width>; // <- Use this to overwrite the width of the full navdrawer
  --ig-nav-drawer-size--mini: <extracted-mini-drawer-width>; // <- Use this to overwrite the width of the mini navdrawer
}

Dark theme overrides for IgxGridComponent

Grid internals often need explicit dark-theme overrides. Use get_component_design_tokens("grid") to discover available tokens, then call create_component_theme with the tokens that differ from the global theme. Apply the returned theme with the tokens:

@include tokens($custom-grid-theme);

Read luminance warnings from theme generation

If create_theme returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use create_custom_palette or define semantic CSS variables such as --surface-1 and --surface-2 in styles.scss instead of relying on a single generated surface color.

Map Component

Adding markers programmatically

The geographic map often requires programmatic series setup once the map instance is available:

const symbolSeries = new IgxGeographicSymbolSeriesComponent();
symbolSeries.dataSource = locations;
symbolSeries.latitudeMemberPath = '<latitude-field>';
symbolSeries.longitudeMemberPath = '<longitude-field>';
symbolSeries.markerType = <resolvedMarkerType>;
symbolSeries.markerBrush = '<resolved-accent-color>';
symbolSeries.markerOutline = '<resolved-accent-color>';
map.series.add(symbolSeries);
// Set zoom bounds to match the geographic region visible in the design image
map.zoomToGeographic({ left: <min-longitude>, top: <top-latitude>, width: <longitude-span>, height: <latitude-span> });

Dark map styling

OpenStreetMap tiles are light by default. For dark themes, apply a CSS filter to the container. Adjust the values to match the map tone in the design image:

.map-container {
  /* tune grayscale (0-1) and brightness (0-1) to match the design */
  filter: grayscale(<0-1>) brightness(<0-1>);
}

Dark Theme Specifics

Use the resolved dark schema for dark themes

@include theme(
  $palette: $resolved-palette,
  $schema: <resolved-dark-schema>
);

CSS custom properties for dark panels

When the design uses multiple dark surface depths (panels, sidebars, cards on a dark background), define reusable semantic tokens using palette references or values derived from the design intent:

:root {
  --surface-primary: <resolved-surface-token>;
  --surface-secondary: <resolved-surface-token>;
  --accent-strong: <resolved-accent-token>;
  --text-primary: <resolved-text-token>;
  --text-secondary: <resolved-text-token>;
}

If create_theme returns a single surface color that doesn't cover all depth levels visible in the design, define additional surface tokens (--surface-1, --surface-2, etc.) for each distinct depth.

Standalone pipes must be imported explicitly

When using Angular pipes in a standalone component template, add the pipe classes to the component imports array:

import { CurrencyPipe, DatePipe, DecimalPipe } from '@angular/common';

@Component({
  imports: [DecimalPipe, DatePipe, CurrencyPipe]
})
export class <ViewComponent> {}