Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): Grid track templates use CSS-var indirection instead of raw inline styles (#3321)

David Petersencb1d8808b3ca
diff --git a/.changeset/grid-template-css-var.md b/.changeset/grid-template-css-var.md
new file mode 100644
index 0000000000..14ca254616
--- /dev/null
+++ b/.changeset/grid-template-css-var.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Grid no longer writes `grid-template-columns`/`grid-auto-rows` as raw inline styles. Track templates now use StyleX dynamic styles (CSS-variable indirection), so consumer `xstyle` overrides — including responsive `@media` overrides — take effect instead of being defeated by inline styles.
+
+@thedjpetersen
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index b43275552a..caa0ace65b 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -17,6 +17,7 @@ export const docs = {
{ guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
{ guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
{ guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
+ { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
],
},
theming: {
@@ -111,6 +112,7 @@ export const docsZh = {
{ guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
{ guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
{ guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
+ { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
],
},
};
@@ -126,6 +128,7 @@ export const docsDense = {
{ guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },
{ guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
{ guidance: false, description: 'Use HStack with wrapping for grids; use Grid instead.' },
+ { guidance: true, description: 'track templates use CSS-var indirection, not inline styles — xstyle/@media overrides of gridTemplateColumns work.' },
],
},
};
diff --git a/packages/core/src/Grid/Grid.test.tsx b/packages/core/src/Grid/Grid.test.tsx
index 46c7937793..2b65835749 100644
--- a/packages/core/src/Grid/Grid.test.tsx
+++ b/packages/core/src/Grid/Grid.test.tsx
@@ -14,6 +14,17 @@ import {render, screen} from '@testing-library/react';
import {Grid} from './Grid';
import {GridSpan} from './GridSpan';
+/**
+ * The track template is applied via a StyleX dynamic style: the element
+ * carries an inline CSS variable while the `grid-template-columns`
+ * declaration lives in a class (so consumer xstyle/@media overrides can
+ * win). `--x-gridTemplateColumns` is the debug-mode variable name emitted
+ * by the StyleX transform in tests.
+ */
+function templateColumns(el: HTMLElement): string {
+ return el.style.getPropertyValue('--x-gridTemplateColumns');
+}
+
describe('Grid', () => {
it('renders with fixed columns', () => {
render(
@@ -25,7 +36,22 @@ describe('Grid', () => {
);
const grid = screen.getByTestId('grid');
expect(grid).toBeInTheDocument();
- expect(grid.style.gridTemplateColumns).toBe('repeat(3, 1fr)');
+ expect(templateColumns(grid)).toBe('repeat(3, 1fr)');
+ });
+
+ it('does not write grid-template-columns as a raw inline style (regression: inline style defeats xstyle/@media overrides)', () => {
+ render(
+ <Grid columns={3} rowHeight={80} data-testid="grid">
+ <div>Item 1</div>
+ </Grid>,
+ );
+ const grid = screen.getByTestId('grid');
+ // The declaration must live in a class (via CSS-var indirection), never
+ // as a raw inline property — inline would beat any consumer override.
+ expect(grid.style.gridTemplateColumns).toBe('');
+ expect(grid.style.gridAutoRows).toBe('');
+ expect(templateColumns(grid)).toBe('repeat(3, 1fr)');
+ expect(grid.style.getPropertyValue('--x-gridAutoRows')).toBe('80px');
});
it('renders with columns object (auto-fill default)', () => {
@@ -36,9 +62,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fill, minmax(250px, 1fr))',
- );
+ expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(250px, 1fr))');
});
it('renders with columns object max (capped via track-max)', () => {
@@ -51,7 +75,7 @@ describe('Grid', () => {
);
const grid = screen.getByTestId('grid');
// Track max caps at (100% - 2 * gap) / 3 — no maxWidth on container
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -59,17 +83,14 @@ describe('Grid', () => {
it('renders with columns object max using columnGap', () => {
render(
- <Grid
- columns={{minWidth: 200, max: 4}}
- columnGap={6}
- data-testid="grid">
+ <Grid columns={{minWidth: 200, max: 4}} columnGap={6} data-testid="grid">
<div>Item 1</div>
<div>Item 2</div>
</Grid>,
);
const grid = screen.getByTestId('grid');
// columnGap takes precedence for track-max calculation
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -118,7 +139,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe('1fr');
+ expect(templateColumns(grid)).toBe('1fr');
});
// --- P1: columns={0} guard (hardening #719) ---
@@ -131,7 +152,7 @@ describe('Grid', () => {
);
const grid = screen.getByTestId('grid');
// columns={0} must not produce repeat(0, 1fr) — should fall back to default
- expect(grid.style.gridTemplateColumns).toBe('1fr');
+ expect(templateColumns(grid)).toBe('1fr');
});
it('falls back to 1fr when columns is negative', () => {
@@ -141,7 +162,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe('1fr');
+ expect(templateColumns(grid)).toBe('1fr');
});
it('uses auto-fill without track-max cap when no max specified', () => {
@@ -151,9 +172,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fill, minmax(200px, 1fr))',
- );
+ expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(200px, 1fr))');
expect(grid.style.maxWidth).toBe('');
});
@@ -213,7 +232,7 @@ describe('Grid', () => {
);
const grid = screen.getByTestId('grid');
// columnGap takes precedence over gap in track-max
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -226,7 +245,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -239,7 +258,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(100px, calc(100% / 3)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -288,9 +307,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fill, minmax(280px, 1fr))',
- );
+ expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
});
it('renders with columns={{minWidth, repeat: "fit"}} using auto-fit', () => {
@@ -301,9 +318,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fit, minmax(280px, 1fr))',
- );
+ expect(templateColumns(grid)).toBe('repeat(auto-fit, minmax(280px, 1fr))');
});
it('renders with columns={{minWidth, repeat: "fill"}} using auto-fill', () => {
@@ -314,9 +329,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fill, minmax(280px, 1fr))',
- );
+ expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
});
it('renders with columns={{minWidth, max}} capping via track-max', () => {
@@ -328,7 +341,7 @@ describe('Grid', () => {
);
const grid = screen.getByTestId('grid');
// Track-max limits columns — grid stays full width
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
);
expect(grid.style.maxWidth).toBe('');
@@ -345,7 +358,7 @@ describe('Grid', () => {
</Grid>,
);
const grid = screen.getByTestId('grid');
- expect(grid.style.gridTemplateColumns).toBe(
+ expect(templateColumns(grid)).toBe(
'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
);
expect(grid.style.maxWidth).toBe('');
diff --git a/packages/core/src/Grid/Grid.tsx b/packages/core/src/Grid/Grid.tsx
index b68ef0acdd..0cd85c0a3c 100644
--- a/packages/core/src/Grid/Grid.tsx
+++ b/packages/core/src/Grid/Grid.tsx
@@ -152,6 +152,19 @@ const baseStyles = stylex.create({
},
});
+// Dynamic track values compile to CSS variables + a class-level declaration
+// (grid-template-columns: var(--x)) instead of a raw inline style, so
+// consumer `xstyle` overrides — including ones inside @media queries — can
+// still win. A raw inline `grid-template-columns` would beat any class.
+const dynamicStyles = stylex.create({
+ templateColumns: (value: string) => ({
+ gridTemplateColumns: value,
+ }),
+ autoRows: (value: number) => ({
+ gridAutoRows: `${value}px`,
+ }),
+});
+
const alignStyles = stylex.create({
start: {
alignItems: 'start',
@@ -413,10 +426,10 @@ export function Grid({
gridTemplateColumns = '1fr';
}
- // Build inline style for dynamic values
+ // Build inline style for dynamic values. Track templates go through
+ // dynamicStyles (CSS-var indirection) so xstyle/@media overrides work;
+ // width/height stay inline as explicit caller-set dimensions.
const inlineStyle: React.CSSProperties = {
- gridTemplateColumns,
- ...(rowHeight != null && {gridAutoRows: `${rowHeight}px`}),
...(width != null && {
width: typeof width === 'number' ? `${width}px` : width,
}),
@@ -446,6 +459,8 @@ export function Grid({
themeProps('grid', {columns: columnsVariant, gap, align, justify}),
stylex.props(
baseStyles.grid,
+ dynamicStyles.templateColumns(gridTemplateColumns),
+ rowHeight != null && dynamicStyles.autoRows(rowHeight),
gap != null && gapStyles[gap],
rowGap != null && rowGapStyles[rowGap],
columnGap != null && columnGapStyles[columnGap],