Skip to content

gotchas.md

Latest commit

 

History

History
105 lines (73 loc) · 4.51 KB

gotchas.md

File metadata and controls

105 lines (73 loc) · 4.51 KB
Raw

Gotchas When Matching a Design

Props and CSS names that do not exist, or that behave unlike their obvious form. Verified against current packages.

Props that do not exist

Written Reality
plotAreaBackground on IgrCategoryChart Not a prop. Style the container's background in CSS.
areaFillOpacity on IgrSparkline Exists on IgrCategoryChart / IgrDataChart only.
roundShape on IgrAvatar Use shape alone.
--ig-button-foreground Button exposes only --ig-button-font-*. Use ::part() or the tokens get_component_design_tokens({ component: 'button' }) returns.
--ig-primary-h / -s / -l No such tokens. Override the shade: --ig-primary-500.

Chart props

Array props need array expressions, not comma-joined strings:

<IgrCategoryChart includedProperties={['revenue', 'cost']} />

markerTypes takes documented marker-type values (an IgrMarkerTypeCollection), not lowercase string arrays. Category charts show a marker at every point by default — if the design shows a bare line or area, you must turn markers off explicitly.

Function-valued props take a reference, not a call: xAxisFormatLabel={labelFormatter}.

Smooth, continuous area charts come from data density first: add points until the shape reads continuous at the rendered size, hide markers, then tune fill opacity and label density. Apply smoothing only if the design itself looks smoothed rather than point-to-point.

Charts collapse inside a flexible CSS Grid track. Set min-height: 0 on the cell and make the chart fill it:

.chart-panel { min-height: 0; }
.chart-panel > * { width: 100%; height: 100%; }

Charts, gauges, and maps also need .register() at module scope. Grid Lite and the igc-*-based components do not.

Styling DV components

Charts, maps, gauges, and sparklines are not igc-* elements — they have no design tokens and no ::part(). Set their appearance through props, resolving values to palette tokens or semantic variables rather than raw hex:

<IgrCategoryChart
  brushes={seriesBrushes}
  outlines={seriesOutlines}
  xAxisLabelTextColor="var(--ig-gray-600)"
  yAxisMajorStroke="var(--ig-gray-200)"
/>

Component specifics

CSS targets the rendered element. igc-card::part(header), never IgrCard.

Nav drawer width comes from two custom properties, both measurable from the image:

igc-nav-drawer {
  --menu-full-width: 15rem;
  --menu-mini-width: 5.5rem;
}

Avatar background is a custom property, so set it on a wrapper for per-instance colors:

<div style={{ '--ig-avatar-background': color } as React.CSSProperties}>
  <IgrAvatar initials="KD" />
</div>

Grid columns are fluid — do not add width. Both IgrGridLiteColumn and IgrColumn size themselves; fixed widths leave dead space right of the last column. If some column truly needs a fixed width, leave at least one without one.

Router-driven tabs are label-only. Inline content inside a routed IgrTab renders in addition to the routed view and pushes it off screen. Keep the outlet outside IgrTabs.

Theming

Theme CSS imports are required — the base theme for core components, plus the grid theme for grids. Do not remove or swap them unless the user wants a variant change.

Dark mode is global. Components read --ig-theme-variant once from :root, so a dark wrapper class cannot make Ignite UI components dark. For one dark panel in a light app, define your own --surface-1 / --surface-2 semantic variables and style your own markup; do not swap the app's theme import. To switch the whole app at runtime, call configureTheme(design, variant) from igniteui-react in addition to swapping the stylesheet.

Multiple dark surface depths rarely come from one generated surface color. Define the depths you need as semantic variables in shared CSS, and read any luminance warning create_theme returns instead of ignoring it.

Maps

Series often have to be added programmatically once the ref exists:

useEffect(() => {
  const map = mapRef.current;
  if (!map) return;
  const series = new IgrGeographicSymbolSeries();
  series.dataSource = locations;
  series.latitudeMemberPath = 'lat';
  series.longitudeMemberPath = 'lon';
  map.series.add(series);
  map.zoomToGeographic({ left, top, width, height });
}, []);

OpenStreetMap tiles are light. For a dark design, filter the container and tune the values to match the image's map tone:

.map-container { filter: grayscale(0.9) brightness(0.6); }