Image Gallery

A flexible image gallery with grid/scroll layouts, lightbox modal, hover effects, and compound component pattern for full customization.

Installation

$ npx shadcn@latest add @orecus/image-gallery

Dependencies:

motionlucide-react

Registry:

@orecus/card@orecus/header@orecus/enhanced-button@orecus/enhanced-empty-state@orecus/use-reduced-motionskeleton

Prop	Type	Default	Description
`images`	`ImageGalleryImage[]`	—	Array of images for data-driven mode
`type`	`'normal' \| 'subtle' \| 'strong' \| 'solid' \| 'none'`	`'normal'`	Glass styling type
`hoverEffect`	`'none' \| 'overlay'`	`'overlay'`	Hover effect - overlay shows alt text with blur
`overlayStyle`	`'dark' \| 'light' \| 'gradient'`	`'dark'`	Overlay style when hoverEffect is 'overlay'
`aspectRatio`	`'square' \| 'video' \| 'wide' \| 'portrait'`	`'video'`	Default aspect ratio for items
`borderRadius`	`'none' \| 'sm' \| 'md' \| 'lg'`	`'md'`	Default border radius for items
`ImageComponent`	`React.ComponentType`	`'img'`	Custom image component (e.g., Next.js Image)
`cardProps`	`Partial<CardProps>`	—	Card component props for customization
`className`	`string`	—	Additional CSS classes

Header with title, icon, description, and action children

Prop	Type	Default	Description
`title`	`string`	—	Title text
`description`	`string`	—	Description text
`icon`	`LucideIcon`	—	Icon component
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	—	Size variant
`children`	`ReactNode`	—	Action elements

Responsive grid layout with standard or bento mode

Prop	Type	Default	Description
`columns`	`2 \| 3 \| 4 \| 5 \| 6`	`4`	Number of columns (standard mode)
`gap`	`'sm' \| 'md' \| 'lg'`	`'md'`	Gap between items
`variant`	`'standard' \| 'bento'`	`'standard'`	Grid layout variant
`bentoLayout`	`ImageGalleryBentoSpan[]`	—	Pattern of col/row spans (repeats for items)
`bentoColumns`	`number \| ImageGalleryGridColumns`	`4`	Column count for bento grid (number or responsive object)
`itemHeight`	`number`	`150`	Base row height in pixels for bento mode
`stagger`	`'none' \| 'fade' \| 'slide-up' \| 'slide-down' \| 'scale' \| 'fade-slide'`	`'none'`	Stagger animation preset for grid items
`staggerDelay`	`number`	`0.05`	Delay between each item animation in seconds
`children`	`ReactNode`	—	ImageGallery.Item elements

Horizontal scroll layout with navigation arrows

Prop	Type	Default	Description
`showArrows`	`boolean`	`true`	Show navigation arrows
`itemWidth`	`number`	`200`	Minimum width of items
`gap`	`'sm' \| 'md' \| 'lg'`	`'md'`	Gap between items

Single image thumbnail

Prop	Type	Default	Description
`image`*	`ImageGalleryImage`	—	Image data object
`index`	`number`	—	Index for ordering/lightbox
`onClick`	`() => void`	—	Click handler
`hoverEffect`	`'none' \| 'overlay'`	—	Override hover effect
`bentoSpan`	`ImageGalleryBentoSpan`	—	Override col/row span for this item in bento mode

Modal viewer with keyboard navigation

Prop	Type	Default	Description
`showThumbnails`	`boolean`	`true`	Show thumbnail strip

Empty state placeholder

Prop	Type	Default	Description
`children`	`ReactNode`	—	Custom empty content