@wix/fast-gallery-vibe

A generic, content-agnostic gallery component built on top of @wix/fast-gallery-core with multiple layout variants and shadCN UI patterns.

Features

• 🎨 Multiple Layout Variants: Grid, Alternating, Slider, Waterfall
• 🔧 Generic & Content-Agnostic: Works with any data type through intelligent data extraction
• 🎯 Custom Item Renderers: Flexible rendering for any component
• ⚡ Performance Optimized: React.useMemo and useCallback optimizations
• 🎨 shadCN UI Patterns: Follows shadCN component architecture with CVA
• 📱 Responsive: Mobile-first responsive design
• 🎯 Simple API: Single component with all functionality included
• 🔄 Pure Layout System: Works with any data type through flexible item rendering

Installation

yarn install @wix/fast-gallery-vibe

Usage

Basic Usage

import { GalleryWrapper } from '@wix/fast-gallery-vibe';

<GalleryWrapper
  items={yourData}
  variant="grid"
  itemRenderer={(item, index) => (
    <YourComponent item={item} index={index}>
      {children}
    </YourComponent>
  )}
  emptyState={<div>No items available</div>}
/>;

With Products

<GalleryWrapper
  items={products}
  variant="alternating"
  itemRenderer={(product) => (
    <Product.Root product={product}>
      <Product.Name />
      <Product.Price />
    </Product.Root>
  )}
/>

With Blog Posts

<GalleryWrapper
  items={blogPosts}
  variant="slider"
  itemRenderer={(post) => (
    <BlogPost.Root post={post}>
      <BlogPost.Title />
      <BlogPost.Excerpt />
    </BlogPost.Root>
  )}
/>

Using the Index Parameter

The index parameter is optional but useful for position-aware features:

<GalleryWrapper
  items={products}
  variant="grid"
  itemRenderer={(product, index) => (
    <Product.Root
      product={product}
      className={index === 0 ? 'featured' : ''}
      data-position={index + 1}
    >
      {index === 0 && <Badge>Featured</Badge>}
      <Product.Name />
      <Product.Price />
    </Product.Root>
  )}
/>

Layout Variants

• grid: 3-column responsive grid layout
• alternating: 3-2-3-2 pattern (odd rows: 3 items, even rows: 2 items)
• slider: Horizontal scrolling carousel
• waterfall: Pinterest-style masonry layout

Pure Layout System

The gallery is a pure layout system that works with any data type. All content rendering is handled by the itemRenderer function, which receives the full original item and can access any fields it needs.

Important: The itemRenderer prop is effectively required. Without it, the gallery will render empty items. In development mode, a warning will be shown if no itemRenderer is provided.

API

GalleryWrapper Props

| Prop | Type | Default | Description | | --------------- | --------------------------------------- | -------- | ------------------------------------------- | | items | T[] | [] | Array of items to display | | variant | LayoutType | "grid" | Layout variant | | itemRenderer | (item: T, index: number) => ReactNode | - | Custom item renderer (effectively required) | | emptyState | ReactNode | - | Content to show when no items | | className | string | - | Additional CSS classes | | ...otherProps | HTMLAttributes<HTMLDivElement> | - | All other standard div attributes |

LayoutType

type LayoutType = 'grid' | 'alternating' | 'slider' | 'waterfall';

CSS Classes

The gallery applies the following CSS classes:

• Wrapper: w-full gallery-layout gallery-{variant}
• Data attribute: data-gallery-variant="{variant}"

Dependencies

• @wix/fast-gallery-core: Core gallery rendering engine
• clsx: Class name utility
• class-variance-authority: Variant management
• react: ^18.3.1
• react-dom: ^18.3.1