Gallery

Lockness UI Component

VIEW

DOCUMENTATION

Gallery

Documentation for the Gallery component.

Installation

bash
deno run -A jsr:@lockness/ui add gallery

Usage

tsx
import { GalleryGrid, GalleryItem } from '@lockness/ui/components'

<GalleryGrid cols={3} gap="md">
  <GalleryItem
    src="/image1.jpg"
    href="/project/1"
    showOverlay
    overlayContent="view"
    alt="Project 1"
  />
  <GalleryItem
    src="/image2.jpg"
    href="/project/2"
    showOverlay
    overlayContent="view"
    alt="Project 2"
  />
</GalleryGrid>

Props

GalleryGrid

PropTypeDefaultDescription
cols2 | 3 | 4 | 5 | 63Number of columns
gap'none' | 'sm' | 'md' | 'lg''md'Gap between items
classstring-Additional class names

GalleryJustified

PropTypeDefaultDescription
rowHeight'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Height of each row (xs=80px, sm=112px, md=144px, lg=192px, xl=256px)
gap'none' | 'sm' | 'md' | 'lg''md'Gap between items
classstring-Additional CSS class names

GalleryJustifiedItem

PropTypeDefaultDescription
srcstringrequiredImage source URL
altstring'Gallery image'Alternative text for the image
ratio'tall' | 'portrait' | 'square' | 'landscape' | 'wide' | 'ultrawide''landscape'Aspect ratio of the image container
rounded'none' | 'default' | 'sm' | 'md' | 'lg''default'Border radius of the image container
classstring-Additional CSS class names

GalleryMasonry

PropTypeDefaultDescription
cols2 | 3 | 4 | 54Number of columns
gap'none' | 'sm' | 'md' | 'lg''md'Gap between items
classstring-Additional class names

GalleryMasonryColumn

PropTypeDefaultDescription
gap'none' | 'sm' | 'md' | 'lg''md'Gap between items in the column
classstring-Additional class names

GalleryItem

PropTypeDefaultDescription
srcstringrequiredImage source URL
altstring'Gallery image'Image alt text
hrefstring-Link URL when clicked
showOverlaybooleanfalseShow hover overlay
overlayContent'view' | 'zoom' | 'expand' | 'none''view'Custom overlay content
overlayTextstring-Custom overlay text
aspect'square' | 'video' | 'auto''square'Image aspect ratio
rounded'none' | 'default' | 'sm' | 'md' | 'lg' | 'full''default'Border radius
classstring-Additional class names
imageClassstring-Additional image class names

VIEW BUTTON ON HOVER

tsx
import { GalleryGrid, GalleryItem } from '@lockness/ui/components'

<GalleryGrid cols={3} gap="md">
  <GalleryItem
    src="/image1.jpg"
    href="/project/1"
    showOverlay
    overlayContent="view"
    alt="Project 1"
  />
  <GalleryItem
    src="/image2.jpg"
    href="/project/2"
    showOverlay
    overlayContent="view"
    alt="Project 2"
  />
  {/* ... more items */}
</GalleryGrid>

OVERLAY VARIANTS

tsx
<GalleryItem showOverlay overlayContent="view" />
<GalleryItem showOverlay overlayContent="zoom" />
<GalleryItem showOverlay overlayContent="expand" />
<GalleryItem showOverlay overlayContent="view" overlayText="Open" />

SQUARED GRID - 4 COLUMNS

Image 1
Image 2
Image 3
Image 4
Image 5
Image 6
Image 7
Image 8
tsx
import { GalleryGrid, GalleryImage } from '@lockness/ui/components'

<GalleryGrid cols={4} gap="md">
  <GalleryImage src="/image1.jpg" aspect="square" />
  <GalleryImage src="/image2.jpg" aspect="square" />
  <GalleryImage src="/image3.jpg" aspect="square" />
  {/* ... more images */}
</GalleryGrid>

MASONRY LAYOUT - 4 COLUMNS

Gallery imageGallery image
Gallery imageGallery imageGallery image
Gallery imageGallery image
Gallery imageGallery imageGallery image
tsx
import {
  GalleryMasonry,
  GalleryMasonryColumn,
  GalleryImage
} from '@lockness/ui/components'

<GalleryMasonry cols={4} gap="md">
  <GalleryMasonryColumn>
    <GalleryImage src="/image1.jpg" aspect="auto" />
    <GalleryImage src="/image2.jpg" aspect="auto" />
    <GalleryImage src="/image3.jpg" aspect="auto" />
  </GalleryMasonryColumn>
  <GalleryMasonryColumn>
    <GalleryImage src="/image4.jpg" aspect="auto" />
    <GalleryImage src="/image5.jpg" aspect="auto" />
  </GalleryMasonryColumn>
  {/* ... more columns */}
</GalleryMasonry>

JUSTIFIED LAYOUT

Justified image 1
Justified image 2
Justified image 3
Justified image 4
Justified image 5
Justified image 6
Justified image 7
Justified image 8
Justified image 9
Justified image 10
Justified image 11
Justified image 12
tsx
import { GalleryJustified, GalleryJustifiedItem } from '@lockness/ui/components'

<GalleryJustified rowHeight="lg" gap="md">
  <GalleryJustifiedItem src="/photo1.jpg" ratio="wide" />
  <GalleryJustifiedItem src="/photo2.jpg" ratio="portrait" />
  <GalleryJustifiedItem src="/photo3.jpg" ratio="landscape" />
  <GalleryJustifiedItem src="/photo4.jpg" ratio="square" />
  <GalleryJustifiedItem src="/photo5.jpg" ratio="ultrawide" />
  <GalleryJustifiedItem src="/photo6.jpg" ratio="tall" />
  {/* Images fill each row and wrap naturally */}
</GalleryJustified>

JUSTIFIED ROW HEIGHT VARIANTS

Extra Small (xs) - 80px

Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image

Medium (md) - 144px

Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
tsx
<GalleryJustified rowHeight="xs" />  {/* 80px row height */}
<GalleryJustified rowHeight="sm" />  {/* 112px row height */}
<GalleryJustified rowHeight="md" />  {/* 144px row height (default) */}
<GalleryJustified rowHeight="lg" />  {/* 192px row height */}
<GalleryJustified rowHeight="xl" />  {/* 256px row height */}

JUSTIFIED ASPECT RATIOS

Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
tsx
// Available ratios:
<GalleryJustifiedItem ratio="tall" />       {/* 2:3 - Vertical */}
<GalleryJustifiedItem ratio="portrait" />   {/* 3:4 - Portrait */}
<GalleryJustifiedItem ratio="square" />     {/* 1:1 - Square */}
<GalleryJustifiedItem ratio="landscape" />  {/* 4:3 - Landscape (default) */}
<GalleryJustifiedItem ratio="wide" />       {/* 16:9 - Wide */}
<GalleryJustifiedItem ratio="ultrawide" />  {/* 21:9 - Ultrawide */}

LIGHTBOX GALLERY

tsx
import {
  GalleryGrid,
  GalleryLightboxItem,
  GalleryLightboxScript
} from '@lockness/ui/components'

// Add the script once in your layout
<GalleryLightboxScript />

// Then use GalleryLightboxItem
<GalleryGrid cols={3} gap="md">
  <GalleryLightboxItem src="/thumb1.jpg" fullSrc="/full1.jpg" />
  <GalleryLightboxItem src="/thumb2.jpg" fullSrc="/full2.jpg" />
  <GalleryLightboxItem src="/thumb3.jpg" fullSrc="/full3.jpg" />
</GalleryGrid>

COLUMN VARIANTS

2 Columns

Gallery image
Gallery image
Gallery image
Gallery image

5 Columns

Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
tsx
<GalleryGrid cols={2}>...</GalleryGrid>
<GalleryGrid cols={3}>...</GalleryGrid>
<GalleryGrid cols={4}>...</GalleryGrid>
<GalleryGrid cols={5}>...</GalleryGrid>
<GalleryGrid cols={6}>...</GalleryGrid>

GAP VARIANTS

gap="none"

Gallery image
Gallery image
Gallery image
Gallery image

gap="sm"

Gallery image
Gallery image
Gallery image
Gallery image

gap="lg"

Gallery image
Gallery image
Gallery image
Gallery image
tsx
<GalleryGrid gap="none">...</GalleryGrid>
<GalleryGrid gap="sm">...</GalleryGrid>
<GalleryGrid gap="md">...</GalleryGrid>  {/* default */}
<GalleryGrid gap="lg">...</GalleryGrid>

ROUNDED VARIANTS

Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
Gallery image
tsx
<GalleryImage rounded="none" />
<GalleryImage rounded="default" />  {/* uses --radius variable */}
<GalleryImage rounded="sm" />
<GalleryImage rounded="md" />
<GalleryImage rounded="lg" />
<GalleryImage rounded="full" />