Skip to content

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

TypeScript

feat(storybook): add masonry gallery examples for XDSGrid (#1523)

Cindy Zhang3b6b1c1c8b90
diff --git a/apps/storybook/stories/GridMasonry.stories.tsx b/apps/storybook/stories/GridMasonry.stories.tsx
new file mode 100644
index 0000000000..520de0086b
--- /dev/null
+++ b/apps/storybook/stories/GridMasonry.stories.tsx
@@ -0,0 +1,305 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
+import {XDSSection} from '@xds/core/Section';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSVStack} from '@xds/core/Stack';
+import {XDSMediaTheme} from '@xds/core/theme';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+} from '@xds/core/theme/tokens.stylex';
+
+const meta: Meta = {
+ title: 'Layout/XDSGrid/Masonry Gallery',
+ tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ─── Styles ────────────────────────────────────────────────────────────────
+
+const styles = stylex.create({
+ card: {
+ position: 'relative',
+ width: '100%',
+ height: '100%',
+ minHeight: 0,
+ overflow: 'clip',
+ borderRadius: radiusVars['--radius-element'],
+ },
+ img: {
+ position: 'absolute',
+ inset: 0,
+ width: '100%',
+ height: '100%',
+ objectFit: 'cover',
+ display: 'block',
+ },
+ overlay: {
+ position: 'absolute',
+ inset: 0,
+ background:
+ 'linear-gradient(to top, rgba(0,0,0,0.7) 0%, transparent 60%)',
+ display: 'flex',
+ flexDirection: 'column',
+ justifyContent: 'flex-end',
+ padding: spacingVars['--spacing-5'],
+ opacity: {
+ default: 0,
+ ':hover': 1,
+ },
+ transition: 'opacity 0.2s ease',
+ },
+ overlayAlwaysOn: {
+ position: 'absolute',
+ inset: 0,
+ background:
+ 'linear-gradient(to top, rgba(0,0,0,0.6) 0%, transparent 50%)',
+ display: 'flex',
+ flexDirection: 'column',
+ justifyContent: 'flex-end',
+ padding: spacingVars['--spacing-5'],
+ },
+ tag: {
+ position: 'absolute',
+ top: spacingVars['--spacing-3'],
+ left: spacingVars['--spacing-3'],
+ backgroundColor: colorVars['--color-accent-muted'],
+ color: colorVars['--color-on-accent'],
+ padding: `${spacingVars['--spacing-0-5']} ${spacingVars['--spacing-2']}`,
+ borderRadius: radiusVars['--radius-element'],
+ fontSize: '11px',
+ fontWeight: 600,
+ textTransform: 'uppercase',
+ letterSpacing: '0.5px',
+ },
+});
+
+// ─── Gallery Data ───────────────────────────────────────────────────────────
+
+interface GalleryImage {
+ src: string;
+ title: string;
+ category: string;
+}
+
+const IMAGES: GalleryImage[] = [
+ {
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/670836735_2461791954280697_1048571955964692895_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=b9DqIpmzyeAQ7kNvwEuVNYV&_nc_oc=Adqx7M8RaKihjC8dSQUH_YjYNSkC7dv34yH96ndekQT74zfo2M6_DMfY-HyXDGEgXYHKMGTPSBWROmTm7oSKCaPg&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=e6YHUehLaMQde9dotUaFJw&_nc_ss=7a30f&oh=00_Af2odB5hzmvCl0lYC5CdnJjHLVeooKOjOOPItWbo1K-2tg&oe=69E6FAAB',
+ title: 'Going places',
+ category: 'Travel',
+ },
+ {
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/672683340_1522469159433922_7776167798061220106_n.png?_nc_cat=101&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=Qpd2UWP6VgEQ7kNvwE-OPni&_nc_oc=AdrBHciJphXt9BtYMnlljRItaFe9QR13GbHjolSlqWeoP37sfn-C414s177sJjM7dk8xymfEjEIkYoEd8bspGCMK&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=Lt9qRH3XlVoT53AL30YKsA&_nc_ss=7a30f&oh=00_Af0tIOpEarNFMfXkSd3D5DVXSUqIKjx9toPEqC89IupM5A&oe=69E6E494',
+ title: 'Making memories',
+ category: 'Home',
+ },
+ {
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/673630979_2366966167048970_507510466630095319_n.png?_nc_cat=103&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=hayXnp1KwWwQ7kNvwE6OwnY&_nc_oc=AdrKqob4CUU2_FrICyqd-B1NVcZ_p6oN45HC6nOs4_NJs-zvYEaj0pRdsvm5oBgVXMMQ-QIYfYEdY7NPSlkmD0VF&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=wxPGUKGIf3ihSjnc_4pFdQ&_nc_ss=7a30f&oh=00_Af3cPR8RHrFZTUPXixsgg3N4iz7847JxcTfJUbK1nisSPg&oe=69E6EAD4',
+ title: 'Seeing things',
+ category: 'Lifestyle',
+ },
+ {
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/669447541_4390219861306657_6002100073104319158_n.png?_nc_cat=108&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=sXKFHmKfCccQ7kNvwGsGpL1&_nc_oc=Adqy06LYMJsViftx1OlQnquClJHettJcc9a0z0BO_mx-979b2VldT8nPRe6J3BwPheu3AlAk6N4LlItaO3vU9xg4&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=H412Z-rQCOugLK-6ss0CDA&_nc_ss=7a30f&oh=00_Af0LKXjbNPwFyK0rA1mnGPK57ctb0rzjTS5jwzXB03oPBw&oe=69E6E58D',
+ title: 'Sharing ideas',
+ category: 'Lifestyle',
+ },
+ {
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/673173617_1842726693762408_2908608806392112143_n.png?_nc_cat=107&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=ipqP09C42_gQ7kNvwHwibG0&_nc_oc=Ado97zfee8ejAhB0dqWyWz4lhsi0K7kf9W9wFBfqvD7cm3mh9le59yGFgbdkzIWO255x4Oe7bwc_vnSh41GvAxTk&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=1ZhYNPWwWg8iLLqOsj0aUg&_nc_ss=7a30f&oh=00_Af340jh-0cJ2G-NDCnGJNrXd-RuAXXawyADjOqNP7tOD7Q&oe=69E712D6',
+ title: 'Being free',
+ category: 'Nature',
+ },
+];
+
+// ─── Gallery Card ───────────────────────────────────────────────────────────
+
+function GalleryCard({
+ image,
+ showOverlay = false,
+}: {
+ image: GalleryImage;
+ showOverlay?: boolean;
+}) {
+ return (
+ <div {...stylex.props(styles.card)}>
+ <img src={image.src} alt={image.title} {...stylex.props(styles.img)} />
+ <span {...stylex.props(styles.tag)}>{image.category}</span>
+ <div
+ {...stylex.props(
+ showOverlay ? styles.overlayAlwaysOn : styles.overlay,
+ )}>
+ <XDSMediaTheme mode="dark">
+ <XDSVStack gap={1}>
+ <XDSText type="label">{image.title}</XDSText>
+ </XDSVStack>
+ </XDSMediaTheme>
+ </div>
+ </div>
+ );
+}
+
+// ─── Stories ────────────────────────────────────────────────────────────────
+
+/**
+ * A Pinterest-style masonry gallery using XDSGrid with row spans.
+ *
+ * The key technique: define explicit row tracks with `gridTemplateRows`,
+ * then use `XDSGridSpan` with different `rows` values to create items of
+ * varying heights. This produces the characteristic staggered masonry layout
+ * without any JavaScript height calculation.
+ */
+export const MasonryGallery: Story = {
+ render: () => (
+ <XDSSection variant="wash" padding={6}>
+ <XDSVStack gap={5}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={2}>Mixed Gallery</XDSHeading>
+ <XDSText type="body">
+ A masonry-style gallery using CSS Grid row spans. Each item spans a
+ different number of rows to create a staggered, Pinterest-like
+ layout.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSGrid columns={3} rowHeight={80} gap={3}>
+ {/* Column 1: 4 + 2 = 6 rows */}
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[0]} />
+ </XDSGridSpan>
+ <XDSGridSpan rows={2}>
+ <GalleryCard image={IMAGES[1]} />
+ </XDSGridSpan>
+
+ {/* Column 2: 2 + 4 = 6 rows */}
+ <XDSGridSpan rows={2}>
+ <GalleryCard image={IMAGES[2]} />
+ </XDSGridSpan>
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[3]} />
+ </XDSGridSpan>
+
+ {/* Column 3: 3 + 3 = 6 rows */}
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[4]} />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[0]} />
+ </XDSGridSpan>
+ </XDSGrid>
+ </XDSVStack>
+ </XDSSection>
+ ),
+};
+
+/**
+ * A denser masonry layout with a 4-column grid and smaller row tracks.
+ * Uses `rowHeight={60}` for unlimited content.
+ */
+export const DenseMasonry: Story = {
+ render: () => {
+ return (
+ <XDSSection variant="wash" padding={6}>
+ <XDSVStack gap={5}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={2}>Dense Masonry</XDSHeading>
+ <XDSText type="body">
+ A 4-column layout with <code>rowHeight={60}</code>. Each item gets
+ a different row span for natural visual rhythm.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSGrid columns={4} rowHeight={60} gap={3}>
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[2]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[0]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={5}>
+ <GalleryCard image={IMAGES[3]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[4]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[1]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[4]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={2}>
+ <GalleryCard image={IMAGES[0]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[2]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[3]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={5}>
+ <GalleryCard image={IMAGES[1]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[4]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={4}>
+ <GalleryCard image={IMAGES[0]} showOverlay />
+ </XDSGridSpan>
+ </XDSGrid>
+ </XDSVStack>
+ </XDSSection>
+ );
+ },
+};
+
+/**
+ * A featured masonry layout combining column and row spans.
+ * The hero image spans 2 columns and 4 rows, with smaller items
+ * arranged around it.
+ */
+export const FeaturedMasonry: Story = {
+ render: () => {
+ return (
+ <XDSSection variant="wash" padding={6}>
+ <XDSVStack gap={5}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={2}>Featured Masonry</XDSHeading>
+ <XDSText type="body">
+ Combines column spans and row spans for a featured hero layout.
+ The primary image spans 2 columns × 5 rows.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSGrid columns={3} rowHeight={70} gap={3}>
+ {/* Hero — 2 cols × 5 rows */}
+ <XDSGridSpan columns={2} rows={5}>
+ <GalleryCard image={IMAGES[2]} showOverlay />
+ </XDSGridSpan>
+
+ {/* Sidebar items */}
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[0]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={2}>
+ <GalleryCard image={IMAGES[1]} showOverlay />
+ </XDSGridSpan>
+
+ {/* Bottom row */}
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[3]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[4]} showOverlay />
+ </XDSGridSpan>
+ <XDSGridSpan rows={3}>
+ <GalleryCard image={IMAGES[1]} showOverlay />
+ </XDSGridSpan>
+ </XDSGrid>
+ </XDSVStack>
+ </XDSSection>
+ );
+ },
+};
diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsx
index ea4b329f89..609b8950b3 100644
--- a/packages/core/src/Grid/XDSGrid.tsx
+++ b/packages/core/src/Grid/XDSGrid.tsx
@@ -97,6 +97,21 @@ export interface XDSGridProps extends XDSBaseProps<HTMLDivElement> {
*/
columnGap?: SpacingStep;
+ /**
+ * Height of each implicit row track in pixels.
+ * Sets `grid-auto-rows` — use with `XDSGridSpan rows={N}` to create
+ * masonry-style layouts where items span varying numbers of rows.
+ *
+ * @example
+ * ```
+ * <XDSGrid columns={3} rowHeight={80} gap={3}>
+ * <XDSGridSpan rows={4}>Tall</XDSGridSpan>
+ * <XDSGridSpan rows={2}>Short</XDSGridSpan>
+ * </XDSGrid>
+ * ```
+ */
+ rowHeight?: number;
+
/**
* Vertical alignment of grid items (align-items).
* @default 'stretch'
@@ -336,6 +351,7 @@ function calculateMaxWidth(
export function XDSGrid({
columns,
minChildWidth = 0,
+ rowHeight,
width,
height,
gap,
@@ -391,6 +407,7 @@ export function XDSGrid({
// Build inline style for dynamic values
const inlineStyle: React.CSSProperties = {
gridTemplateColumns,
+ ...(rowHeight != null && {gridAutoRows: `${rowHeight}px`}),
...(calculatedMaxWidth != null && {maxWidth: `${calculatedMaxWidth}px`}),
...(width != null && {
width: typeof width === 'number' ? `${width}px` : width,