Gallery
Lockness UI Component
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
| Prop | Type | Default | Description |
|---|---|---|---|
| cols | 2 | 3 | 4 | 5 | 6 | 3 | Number of columns |
| gap | 'none' | 'sm' | 'md' | 'lg' | 'md' | Gap between items |
| class | string | - | Additional class names |
GalleryJustified
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 |
| class | string | - | Additional CSS class names |
GalleryJustifiedItem
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | required | Image source URL |
| alt | string | '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 |
| class | string | - | Additional CSS class names |
GalleryMasonry
| Prop | Type | Default | Description |
|---|---|---|---|
| cols | 2 | 3 | 4 | 5 | 4 | Number of columns |
| gap | 'none' | 'sm' | 'md' | 'lg' | 'md' | Gap between items |
| class | string | - | Additional class names |
GalleryMasonryColumn
| Prop | Type | Default | Description |
|---|---|---|---|
| gap | 'none' | 'sm' | 'md' | 'lg' | 'md' | Gap between items in the column |
| class | string | - | Additional class names |
GalleryItem
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | required | Image source URL |
| alt | string | 'Gallery image' | Image alt text |
| href | string | - | Link URL when clicked |
| showOverlay | boolean | false | Show hover overlay |
| overlayContent | 'view' | 'zoom' | 'expand' | 'none' | 'view' | Custom overlay content |
| overlayText | string | - | Custom overlay text |
| aspect | 'square' | 'video' | 'auto' | 'square' | Image aspect ratio |
| rounded | 'none' | 'default' | 'sm' | 'md' | 'lg' | 'full' | 'default' | Border radius |
| class | string | - | Additional class names |
| imageClass | string | - | 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
SQUARED GRID - 4 COLUMNS
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
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
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
Medium (md) - 144px
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
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
5 Columns
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"
gap="sm"
gap="lg"
tsx
<GalleryGrid gap="none">...</GalleryGrid>
<GalleryGrid gap="sm">...</GalleryGrid>
<GalleryGrid gap="md">...</GalleryGrid> {/* default */}
<GalleryGrid gap="lg">...</GalleryGrid>ROUNDED VARIANTS
tsx
<GalleryImage rounded="none" />
<GalleryImage rounded="default" /> {/* uses --radius variable */}
<GalleryImage rounded="sm" />
<GalleryImage rounded="md" />
<GalleryImage rounded="lg" />
<GalleryImage rounded="full" />